home *** CD-ROM | disk | FTP | other *** search
/ Gold Medal Software 3 / Gold Medal Software - Volume 3 (Gold Medal) (1994).iso / bbsutils / smb_110a.arj / SMB.TXT < prev    next >
Text File  |  1994-03-28  |  112KB  |  2,877 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.                      Synchronet Message Base Specification
  21.                                  Version 1.10
  22.                                Updated 03/28/94
  23.  
  24.                         Copyright 1994 Digital Dynamics
  25.  
  26.                                   PO Box 501
  27.                              Yorba Linda, CA 92686
  28.  
  29.                  Voice: 714-529-6328   BBS: 714-529-9525 V.32/V.32bis
  30.                    FAX: 714-529-9721            529-9547 V.FC
  31.                   FIDO: 1:103/705               529-9721 ZyXEL
  32.  
  33. Table of Contents
  34. =================
  35. &&Contents
  36.  
  37. Introduction....................................................@@INTRO___
  38. Implementation Levels...........................................@@IMPLEVEL
  39. Definitions.....................................................@@DEFINES_
  40.         Acronyms................................................@@ACRONYMS
  41.         Data Types..............................................@@DATATYPE
  42. File Formats....................................................@@FILEFORM
  43.         Index.....................(*.SID).......................@@SID_FORM
  44.         Header....................(*.SHD).......................@@SHD_FORM
  45.         Header Allocation.........(*.SHA).......................@@SHA_FORM
  46.         Data......................(*.SDT).......................@@SDT_FORM
  47.         Data Allocation...........(*.SDA).......................@@SDA_FORM
  48.         CRC History...............(*.SCH).......................@@SCH_FORM
  49. Header Field Types..............................................@@HFIELD_T
  50. Data Field Types................................................@@DFIELD_T
  51. Messsage Attributes.............................................@@ATTRBITS
  52. Translation Types...............................................@@XLATTYPE
  53. Agent Types.....................................................@@AGENTTYP
  54. Network Types...................................................@@NETWORKS
  55. Media Types.....................................................@@MEDIATYP
  56. Message Storage Protocol........................................@@STORPROT
  57. Message Retrieval Protocol......................................@@READPROT
  58. SMBUTIL.........................................................@@SMBUTIL_
  59. CHKSMB..........................................................@@CHKSMB__
  60. SMBLIB (C library)..............................................@@SMBLIB__
  61.         Data Types and Constants..(SMBDEFS.H)...................@@SMBDEFS_
  62.         Global Variables..........(SMBVARS.C)...................@@SMBVARS_
  63.         Function Prototypes.......(SMBLIB.H)....................@@SMBLIB.H
  64.         Library Functions.........(SMBLIB.C)....................@@SMBLIB.C
  65. Bibliography....................................................@@BIBLIOGR
  66. Implementations.................................................@@IMPLEMEN
  67.  
  68. Introduction
  69. ============
  70. &&Introduction
  71. $$INTRO___
  72.  
  73. Q. What is SMB?
  74.  
  75. A. SMB (Synchronet Message Base) is a technical specification for the storage
  76.    format of electronic mail messages. These e-mail messages may all be
  77.    contained in one database, or, more commonly, separated into catagorized
  78.    databases. These message databases (or message bases) are also referred to
  79.    as 'sub-boards', 'forums', 'conferences,' and 'SIGs'. The messages may be
  80.    directed to an individual person, sent to a group of individuals, or sent
  81.    to everyone who can read messages in that message base. Messages may be
  82.    created and read soley at one physical location, or imported from and
  83.    exported to a message network that may span continents. Message bases that
  84.    are connected to a message network are often called 'echoes'.
  85.  
  86.  
  87. Q. Why SMB?
  88.  
  89. A. The Synchronet Message Base is designed to store high volumes of messages
  90.    while maintaining optimum search, retrieval, and creation performance.
  91.    These messages are not defined as merely text. In addition to text, SMB
  92.    defines the storage of digitized sound, MIDI, graphics, fonts, animation,
  93.    as well as other multimedia data and triggers for localized multimedia.
  94.    SMB thrives on a multi-user environment where messages are being created,
  95.    read, modified, and deleted by multiple tasks simultaneously. With the
  96.    large message networks of today being the rule, rather than the exception,
  97.    and high volumes of messages being imported on a daily, sometimes hourly
  98.    basis, creation and deletion speed is of the utmost importance. This is
  99.    where SMB really shines. Being extensible enough to handle message formats
  100.    from networks of today and tomorrow, and fast enough to import more messages
  101.    that humanly readable, the SMB format will more than meet your message
  102.    storage needs.
  103.  
  104.  
  105. Q. Why a specification?
  106.  
  107. A. Message bases are often accessed and modified by a number of different
  108.    programs. Often these programs are developed by individuals or companies
  109.    other than the original designer of the message base format. This
  110.    specification is an attempt to aid developers in creating programs that
  111.    access or modify a message base stored in the SMB format.
  112.  
  113.  
  114. Q. Who can use this specification?
  115.  
  116. A. Anyone that has interest in the Synchronet Message Base format at either
  117.    an educational or professional level. Specifically, software developers
  118.    interested or currently involved in the development of message readers,
  119.    editors, echomail (toss/scan) programs, message transfer agents (MTAs),
  120.    network gateways, and bulletin board systems. Much of the information in
  121.    this specification is intended for those with preexisting programming
  122.    knowledge, so those with little or no programming experience may find it
  123.    hard to comprehend.
  124.  
  125.  
  126. Q. What does the SMB specification include?
  127.  
  128. A. The text you are reading is part of the SMB specification: a single text
  129.    document that defines the storage format of each of the six files of an
  130.    SMB format message base and how they are related to each other.
  131.  
  132.    Included with this specification is C source code to be used as an example
  133.    to programmers of how to access an SMB format message base and public domain
  134.    library functions (SMBLIB) that can be compiled and linked into programs
  135.    that access an SMB format message base developed by third parties. An SMB
  136.    utility program (SMBUTIL) is also included with C source code as an example
  137.    of how to use the SMBLIB functions.
  138.  
  139.  
  140. Q. Where did the SMB specification come from?
  141.  
  142. A. Digital Dynamics (southern California based software development company)
  143.    released "Synchronet Multinode BBS Software Version 1a" in June of 1992 as
  144.    one of the first BBS packages to be designed from the ground-up to operate
  145.    in a multinode environment with incredible speed and reliability, with a
  146.    large suite of multinode specific features and design innovations.
  147.  
  148.    The original message base format was designed with localized messaging and
  149.    low volume message networks in mind. By January of 1993, it was clear that
  150.    high volume message networks (FidoNet, RelayNet, Usenet, etc.) were the
  151.    preference of most BBS users and a new message base format was required to
  152.    allow for high volume message storage, improved storage, retrieval, and
  153.    maintenance performance, as well as lower storage space requirements.
  154.  
  155.    Rather than introduce another new message format, Digital Dynamics sought
  156.    to implement an existing public specification for a format that would meet
  157.    current and future message storage needs. More than a few specifications
  158.    were seriously considered at one time or another, but after careful
  159.    examination, design flaws and lack of extensibility eliminated them from the
  160.    long term plans of Digital Dynamics and Synchronet BBS Software. Thus began
  161.    the design of the "Synchronet Message Base" (SMB) format.
  162.  
  163.    At the request of many message related program developers, Digital Dynamics
  164.    created and released the SMB specification before the release of "Synchronet
  165.    Version 2.00" to allow lead-time on developing support programs for the new
  166.    format.
  167.  
  168.    Digital Dynamics strongly encourages developers of message related programs
  169.    (including software that directly competes with Synchronet or other Digital
  170.    Dynamics products) to implement support for SMB. Though this is a public
  171.    specification and Digital Dynamics encourages developer suggestions, it will
  172.    remain under the sole control of Digital Dynamics unless specifically stated
  173.    otherwise in a future revision of this specification.
  174.  
  175.    Digital Dynamics requests that any organizations that wish to adopt or
  176.    ratify this specification, in part or whole, notify Digital Dynamics through
  177.    any of the contact methods listed at the beginning of this document.
  178.  
  179.  
  180. Q. How does SMB store messages?
  181.  
  182. A. Each message base is stored in a set of six binary files. The base filename
  183.    (maximum of eight characters) is the same for all six files of the same
  184.    message base and unique amoung the filenames of other message bases. The six
  185.    files each have a different three character extension. The first character
  186.    of the extension is always the letter 'S' (for SMB), while the second and
  187.    third characters define the contents of the file.
  188.  
  189.    Two of the six files associated with each message base are not recreatable
  190.    and therefore are the most important when considering data integrity. These
  191.    two files are the data file (with a .SDT extension) and variable length
  192.    header file (.SHD extension). Both of these files use 256 byte blocks and
  193.    have associated block allocation tables (stored in .SDA and .SHA
  194.    respectively) so that deleted message blocks may be used by new messages
  195.    without creating odd sized unused 'holes' in the files. The block allocation
  196.    table files (.SDA and .SHA) can be recreated with the information stored in
  197.    the header (.SHD) file.
  198.  
  199.    For fast indexing, there is a small fixed length index file (with a .SID
  200.    extension). This file allows for the immediate location of message header
  201.    records based on sender's name or user number, recipient's name or user
  202.    number, subject, message number, or message attributes. This file can be
  203.    recreated with the data stored in the header (.SHD) file.
  204.  
  205.    The last file is an optional CRC history (.SCH) file. It contains 32-bit
  206.    CRCs of a configurable number of messages imported or created locally. This
  207.    is to help eliminate duplicate messages created by user or program error.
  208.    The CRC history file can be recreated with the combination of information
  209.    stored in the data (.SDT) and header (.SHD) files.
  210.  
  211. Q. How fast do messages import into an SMB message base?
  212.  
  213. A. This is a very important question for systems for that import large volumes
  214.    of messages. Of course, the answer depends on the storage format which you
  215.    are importing from, the average length of messages, the design of the
  216.    program which is peforming the import process, as well as the hardware and
  217.    system software being used. What's important is that SMB will allow the
  218.    fastest import process possible with any given combination of the above
  219.    factors.
  220.  
  221.    Since system storage capacity is rarely infinite, neither is the number
  222.    of messages which can be stored. System operators must define the maximum
  223.    number of messages to be stored in a message base, the maximum age of the
  224.    messages in that message base, or a combination of both. Generally, the
  225.    smaller the number of messages stored in a message base, the faster the
  226.    import process. The SMB format is flexible enough to support multiple
  227.    levels of import performance based on optimizations for storage space or
  228.    speed. Most system operators will almost invariably choose speed over
  229.    space, but which choices are available is determined by the importing
  230.    program.
  231.  
  232.  
  233. Q. How much storage is required for an SMB message base?
  234.  
  235. A. The biggest factor in determining storage requirements for a message base
  236.    is the maximum number of messages to be stored in the base (defined by the
  237.    system operator) and the average size of each message. The minimum required
  238.    storage for a message base is 32 bytes plus 535 bytes per message (539 bytes
  239.    per message if duplicate message checking is used).
  240.  
  241.    The SMB format is designed to be "self-packing", meaning purged (deleted)
  242.    message header and data blocks will be used automatically by new messages.
  243.    Relying solely on self-packing, an SMB format message base will never
  244.    "shrink" in size. This is not to say that it will continually "grow" in
  245.    size, but that without specific packing procedures, deleted message blocks
  246.    may remain unused for extended periods of time, meanwhile using some amount
  247.    of storage space that could be freed using specific packing procedures.
  248.  
  249.    Limiting the maximum age of messages in an SMB message base is another way
  250.    to control the storage requirements. While maximum message age definition is
  251.    optional, the definition of the maximum number of messages is not.
  252.  
  253. Q. How many messages can be stored per SMB message base?
  254.  
  255. A. Without considering storage limitations or message data lengths greater than
  256.    256, the theoretical maximum number of messages that can be stored in a
  257.    single SMB message base is 16.7 million. Considering the variable length
  258.    nature of message and header data, it is suggested that the system operator
  259.    allow no more than 1 million messages per base.
  260.  
  261.    To determine an estimated maximum number of messages for a message base
  262.    using the average message data length as a factor, use the following
  263.    formula:
  264.  
  265.    4.2 billion divided by the average message length rounded up to be evenly
  266.    divisible by 256.
  267.  
  268.    If the average message data length is 1500 bytes, the estimated maximum
  269.    number of messages would be 2,734,375 (4.2 billion divided by 1536).
  270.  
  271. Implementation Levels
  272. =====================
  273. &&Implementation Levels
  274. $$IMPLEVEL
  275. The SMB format can be implemented to varying degrees between programs without
  276. creating compatibilty issues. Rather than have developers specifically state
  277. which features they have and have not implemented, we have defined five levels
  278. of implementation (represented by Roman numerals I through VII). For a program
  279. or software package to meet an implementation level, it must have all of the
  280. features listed for that level and all of those for each level below it. The
  281. minimum suggested imlementation is level I. The SMBUTIL program included with
  282. this specification is an example of a level I implementation.
  283.  
  284. Level I
  285. -------
  286. The minimum suggested level of implementation. Messages contain merely ASCII
  287. text displayable on an ANSI terminal. Messages can be added to the message
  288. base and if the maximum number of messages is exceeded, messages are removed
  289. or marked for deletion.
  290.  
  291. The SMBUTIL program included with this specification, is the perfect example
  292. of level I implementation.
  293.  
  294. Level II
  295. --------
  296. The addition of file attachments, multiple index/header entries per message
  297. (multiple destinations), multiple text bodies for the separation of message
  298. text and tag/origin lines (for example), forwarding, threading, and specific
  299. FidoNet kludge header field support makes this level of implementation more
  300. realistic for bulletin board system and EchoMail software implementation.
  301.  
  302. Synchronet Multinode BBS Software v2.00 has a level II implementation of this
  303. specification.
  304.  
  305. Level III
  306. ---------
  307. This implementation adds support for translation strings defined later in this
  308. document for data compression, encryption, escaping, and encoding. This level
  309. is still limited to basic ASCII text and ANSI escape sequence entry and
  310. retrieval.
  311.  
  312. Level IV
  313. --------
  314. The storage and retrieval of embedded and attached images is added in this
  315. level of implementation. Supported images are limited to single binary or text
  316. data blocks that can be displayed or transferred to the user (automatically,
  317. or by request) if their display and translation protocols define specific
  318. support for the image type.
  319.  
  320. Level V
  321. -------
  322. This level of implementation adds support for embedded and attached sound data.
  323. This includes digitized sound and MIDI data. Supported sounds are limited to
  324. single binary or text data blocks that can be played or transferred to the user
  325. (automatically or by request) if their presentation and translation protocols
  326. define specific support for the sound type.
  327.  
  328. Level VI
  329. --------
  330. Localized sound and image data can be triggered by messages stored and
  331. retrieved in an implementation of this level.
  332.  
  333. Level VII
  334. ---------
  335. Complete multimedia support is reached in this implementation level with
  336. support for embedded and attached animation, sound, and video data.
  337.  
  338.  
  339. Definitions
  340. ===========
  341. &&Definitions
  342. $$DEFINES_
  343.  
  344. Control Characters
  345. ------------------
  346. When specifying control characters (ASCII 1 through 31), the caret symbol "^"
  347. or the abreviation "ctrl-" followed by a character will be used to indicate the
  348. value. ^A is equivalent to ASCII 1, ^B ASCII 2, etc. The case of the control
  349. character is not significant (i.e. ^z and ^Z are equivalent). The control
  350. character ^@ (ASCII 0) will be specified as NULL or 0.
  351.  
  352.  
  353. Hexidecimal
  354. -----------
  355. Base sixteen numbering system which includes the digits 0-9 and A-F.
  356. Hexidecimal numbers are represented in this document with a prefix of "0x" or
  357. "\x" or a suffix of "h". Hexidecimal letter digits are not case sensitive
  358. (i.e. the number 0xff is the same as 0xFF).
  359.  
  360.  
  361. File dump
  362. ---------
  363. When example file dumps are displayed, the format is similar to that of the
  364. output from the DOS DEBUG program. With the exception of the ASCII characters,
  365. all numbers are in hexidecimal.
  366.  
  367. Offset    Byte values                                          ASCII characters
  368.  
  369. 000000    53 4D 42 1A 10 01 20 00   F4 01 00 00 F4 01 00 00    SMB... .⌠...⌠...
  370. 000010    20 00 00 00 D0 07 00 00   D0 07 00 00 00 00 00 00     ...╨...╨.......
  371.  
  372.  
  373. Bit values
  374. ----------
  375. Bit (or flag) values are represented in C notation as (1<<x) where x is the bit
  376. number. (i.e. bit number 7 (1<<7) is the same as 0x80).
  377.  
  378.  
  379. Word storage
  380. ------------
  381. All words (16-bit) and double words (32-bit) are stored in Intel 80x86 (little
  382. endian) format with bytes stored from low to high (reverse of the Motorola
  383. 680x0 word storage format).
  384.  
  385. A 16-bit word with the value 1234h is stored as 34h 12h.
  386.  
  387. Translation strings
  388. -------------------
  389. Translation strings (xlat variables) are arrays of words (16-bit) in the order
  390. of the original storage translation. The last translation type is followed by a
  391. 16-bit zero (defined later as XLAT_NONE). If there are no translations, then
  392. the first and only element of the array is XLAT_NONE.
  393.  
  394. When translating data upon retrieval, the translation order must be reversed
  395. to obtain the proper data.
  396.  
  397. Acronyms:
  398. ========
  399. &&Definition of Acronyms
  400. $$ACRONYMS
  401.  
  402. ANSI            American National Standards Institute
  403. ASCII           American Standard Code for Information Interchange
  404. BBS             Bulletin Board System
  405. C               The C programming language as defined by ANSI X3.159-1989
  406. CR              Carriage Return character (ASCII 13)
  407. CRC             Cyclic Redundancy Check
  408. CRC-16          Standard 16-bit CRC using 1021h polynomial
  409. CRC-32          Standard 32-bit CRC using EDB88320h polynomial
  410. CRLF            Carriage Return character followed by a Line Feed character
  411. FSC             FidoNet Standards Commitee (FTS proposal)
  412. FTN             FidoNet Technology Network
  413. FTS             FidoNet Technical Standard
  414. LF              Line Feed character (ASCII 10)
  415. QWK             Compressed message packet format for message reading/networking
  416. RFC             Request for Comments
  417. SMB             Synchronet Message Base
  418. UT              Universal Time (formerly called "Greenwhich Mean Time")
  419.  
  420. Data types
  421. ==========
  422. &&Definition of Data Types
  423. $$DATATYPE
  424.  
  425. uchar           Unsigned 8-bit value (0 through 255).
  426.                 C example:
  427.  
  428.                 #define uchar unsigned char
  429.  
  430.  
  431. short           Signed 16-bit value (-32768 through 32767).
  432.                 "short" is a C keyword indicating "short int".
  433.  
  434.  
  435. ushort          Unsigned 16-bit value (0 through 65535).
  436.                 C example:
  437.  
  438.                 #define ushort unsigned short
  439.  
  440.  
  441. ulong           Unsigned 32-bit value (0 through 4294967295).
  442.                 C example:
  443.  
  444.                 #define ulong unsigned long
  445.  
  446.  
  447. time_t          Unsigned 32-bit value.
  448.                 Seconds since 00:00 Jan 01 1970 (Unix format).
  449.                 Used for all time/date storage in SMB as part of the when_t
  450.                 data type. This time format will support dates through the year
  451.                 2105.
  452.                 time_t is defined by ANSI C as a long (signed) which can
  453.                 limit its date support to the year 2038 depending on the
  454.                 library routines used.
  455.  
  456.  
  457. ASCII           String (aka character array) of 8-bit ASCII characters.
  458.                 Characters with the bit 7 set (80h through FFh) represent
  459.                 the IBM PC extended ASCII character set. When data or header
  460.                 fields of this type are stored in the header, a NULL
  461.                 terminator may or may not be present.
  462.                 C example:
  463.  
  464.                 uchar str[80];
  465.  
  466.  
  467. ASCIIZ          ASCII string with (non-optional) NULL terminator.
  468.                 C example:
  469.  
  470.                 uchar str[81];
  471.  
  472. nulstr          ASCII string immediately terminated by NULL.
  473.                 C example:
  474.  
  475.                 uchar *nulstr="";
  476.  
  477.  
  478. undef           Data buffer with undefined contents.
  479.                 C example:
  480.  
  481.                 uchar buf[BUF_LEN];
  482.  
  483. when_t          Date/Time stamp including time-zone adjustment information.
  484.                 C example:
  485.  
  486.                 typedef struct {
  487.  
  488.                     time_t  time;   // Time stamp (in local time)
  489.                     short   zone;   // Zone constant or Minutes (+/-) from UT
  490.  
  491.                     } when_t;
  492.  
  493.                 time:
  494.  
  495.                 A time value of 0 is invalid and indicates an uninitialized
  496.                 time stamp.
  497.  
  498.                 Time stamps are always stored in local time. i.e. Regardless
  499.                 of what time zone, Jan 1st 1994 00:00 will always be stored
  500.                 as 2D250350h.
  501.  
  502.                 zone:
  503.  
  504.                 If the zone is the range -720 to +720, it represents the number
  505.                 of minutes east or west of UT. Values in this range should only
  506.                 be used for time zones not otherwise represented here.
  507.  
  508.                 If the zone is greater than 720 or less than -720, then the
  509.                 following bits have special meaning:
  510.  
  511.                 (1<<12)         // Non-US time zone     (east of UT)
  512.                 (1<<13)         // Non-US time zone     (west of UT)
  513.                 (1<<14)         // U.S. time zone
  514.                 (1<<15)         // Daylight savings
  515.  
  516.                 The lower 12 bits (0 through 11) contain the number of minutes
  517.                 east or west of UT (not accounting for daylight savings).
  518.  
  519.                 If the time zone is one specified in the U.S. Uniform Time Act,
  520.                 the following values represent the zone:
  521.  
  522.                 AST 0x40F0      // Atlantic             (-04:00)
  523.                 EST 0x412C      // Eastern              (-05:00)
  524.                 CST 0x4168      // Central              (-06:00)
  525.                 MST 0x41A4      // Mountain             (-07:00)
  526.                 PST 0x41E0      // Pacific              (-08:00)
  527.                 YST 0x421C      // Yukon                (-09:00)
  528.                 HST 0x4258      // Hawaii/Alaska        (-10:00)
  529.                 BST 0x4294      // Bering               (-11:00)
  530.  
  531.                 With bit 15 set, the following values represent the same zone
  532.                 with the presence of daylight savings:
  533.  
  534.                 ADT 0xC0F0      // Atlantic             (-03:00)
  535.                 EDT 0xC12C      // Eastern              (-04:00)
  536.                 CDT 0xC168      // Central              (-05:00)
  537.                 MDT 0xC1A4      // Mountain             (-06:00)
  538.                 PDT 0xC1E0      // Pacific              (-07:00)
  539.                 YDT 0xC21C      // Yukon                (-08:00)
  540.                 HDT 0xC258      // Hawaii/Alaska        (-09:00)
  541.                 BDT 0xC294      // Bering               (-10:00)
  542.  
  543.                 The following non-standard time zone specifications may also be
  544.                 used:
  545.  
  546.                 MID 0x2294      // Midway               (-11:00)
  547.                 VAN 0x21E0      // Vancouver            (-08:00)
  548.                 EDM 0x21A4      // Edmonton             (-07:00)
  549.                 WIN 0x2168      // Winnipeg             (-06:00)
  550.                 BOG 0x212C      // Bogota               (-05:00)
  551.                 CAR 0x20F0      // Caracas              (-04:00)
  552.                 RIO 0x20B4      // Rio de Janeiro       (-03:00)
  553.                 FER 0x2078      // Fernando de Noronha  (-02:00)
  554.                 AZO 0x203C      // Azores               (-01:00)
  555.                 LON 0x1000      // London               (+00:00)
  556.                 BER 0x103C      // Berlin               (+01:00)
  557.                 ATH 0x1078      // Athens               (+02:00)
  558.                 MOS 0x10B4      // Moscow               (+03:00)
  559.                 DUB 0x10F0      // Dubai                (+04:00)
  560.                 KAB 0x110E      // Kabul                (+04:30)
  561.                 KAR 0x112C      // Karachi              (+05:00)
  562.                 BOM 0x114A      // Bombay               (+05:30)
  563.                 KAT 0x1159      // Kathmandu            (+05:45)
  564.                 DHA 0x1168      // Dhaka                (+06:00)
  565.                 BAN 0x11A4      // Bangkok              (+07:00)
  566.                 HON 0x11E0      // Hong Kong            (+08:00)
  567.                 TOK 0x121C      // Tokyo                (+09:00)
  568.                 SYD 0x1258      // Sydney               (+10:00)
  569.                 NOU 0x1294      // Noumea               (+11:00)
  570.                 WEL 0x12D0      // Wellington           (+12:00)
  571.  
  572. fidoaddr_t      FidoNet address stored as four ushorts that represent the zone,
  573.                 network, node, and point (in that order).
  574.                 C example:
  575.  
  576.                 typedef struct {
  577.  
  578.                     ushort zone,
  579.                            net,
  580.                            node,
  581.                            point;
  582.  
  583.                     } fidoaddr_t;
  584.  
  585.  
  586. typestr_t       ASCIIZ string with ushort type prefix.
  587.                 C example:
  588.  
  589.                 typedef struct {
  590.  
  591.                     ushort  type;   // Specifier for type of 'str'
  592.                     uchar   str[];  // ASCIIZ filename or other string data
  593.  
  594.                     } typestr_t;
  595.  
  596.  
  597. mattach_t       File attachment information with type prefix, translation
  598.                 string, and filename.
  599.                 C example:
  600.  
  601.                 typedef struct {
  602.  
  603.                     ushort  type;   // Attachment type
  604.                     ushort  xlat[]; // Translations of data in attachment
  605.                     uchar   str[];  // ASCIIZ filename
  606.  
  607.                     } mattach_t;
  608.  
  609. vattach_t       Video file attachment information with type, compression,
  610.                 translation string, and filename.
  611.                 C example:
  612.  
  613.                 typedef struct {
  614.  
  615.                     ushort  type;   // Attachment type
  616.                     ushort  comp;   // Compression method
  617.                     ushort  xlat[]; // Translations of data in attachment
  618.                     uchar   str[];  // ASCIIZ filename
  619.  
  620.                     } vattach_t;
  621.  
  622. mtext_t         Message text with translation string prefix.
  623.                 C example:
  624.  
  625.                 typedef struct {
  626.  
  627.                     ushort  xlat[]; // Translations of text
  628.                     uchar   text[]; // Actual text data
  629.  
  630.                     } mtext_t;
  631.  
  632.  
  633. ftext_t         Formatted message text with translation string prefix and
  634.                 format type.
  635.                 C example:
  636.  
  637.                 typedef struct {
  638.  
  639.                     ushort  type;   // See Image Types for valid types
  640.                     ushort  xlat[]; // Translations of data
  641.                     uchar   data[]; // Actual formatted text data
  642.  
  643.                     } ftext_t;
  644.  
  645.  
  646. membed_t        Embedded data with type prefix, translation string, and ASCIIZ
  647.                 description.
  648.                 C example:
  649.  
  650.                 typedef struct {
  651.  
  652.                     ushort  type;   // Specifier for type of 'dat'
  653.                     ushort  xlat[]; // Translations of embedded data
  654.                     uchar   name[]; // ASCIIZ char description of embedded data
  655.                     uchar   dat[];  // Binary data
  656.  
  657.                     } membed_t;
  658.  
  659. vembed_t        Embedded video data with type, compression method, translation
  660.                 string, and ASCIIZ description.
  661.                 C example:
  662.  
  663.                 typedef struct {
  664.  
  665.                     ushort  type;   // Specifier for type of 'dat'
  666.                     ushort  comp;   // Compression method
  667.                     ushort  xlat[]; // Translations of embedded data
  668.                     uchar   name[]; // ASCIIZ char description of embedded data
  669.                     uchar   dat[];  // Binary data
  670.  
  671.                     } vembed_t;
  672.  
  673. File formats
  674. ============
  675. &&File Formats
  676. $$FILEFORM
  677. &&Index (*.SID) File Format
  678. $$SID_FORM
  679.  
  680. Index File (*.SID)
  681. ------------------
  682. The index file for each message base contains one record per message in the
  683. base. Each record is fixed length using the following format:
  684.  
  685. Index Record:
  686. ------------
  687. C example:
  688.  
  689. typedef struct {
  690.  
  691.     ushort  to;             // 16-bit CRC of recipient name (lower case) or #
  692.     ushort  from;           // 16-bit CRC of sender name (lower case) or #
  693.     ushort  subj;           // 16-bit CRC of title/subject (lower case)
  694.     ushort  attr;           // attributes (read, permanent, etc. flags)
  695.     ulong   offset;         // offset into header file
  696.     ulong   number;         // message number
  697.     time_t  time;           // import date/time stamp (Unix format)
  698.  
  699.     } idxrec_t;
  700.  
  701.  
  702. Example file dump (16 messages starting with message number 15):
  703. ---------------------------------------------------------------
  704. 000000    36 4F 13 07 2A 77 00 00   20 00 00 00 0F 00 00 00    6O..*w.. .......
  705. 000010    BE 62 76 2C 36 4F 46 0A   7F B2 00 00 20 01 00 00    ╛bv,6OF.▓.. ...
  706. 000020    10 00 00 00 C7 29 78 2C   36 4F 70 6F 46 FF 00 00    ....╟)x,6OpoF ..
  707. 000030    20 02 00 00 11 00 00 00   AD D3 7A 2C 70 6F 13 07     .......¡╙z,po..
  708. 000040    46 FF 00 00 20 03 00 00   12 00 00 00 D6 F8 7F 2C    F .. .......╓°,
  709. 000050    36 4F E1 EA E7 E9 00 00   20 04 00 00 13 00 00 00    6OßΩτΘ.. .......
  710. 000060    1E 7B 85 2C 37 0D 2E DF   4D 79 00 00 20 05 00 00    .{à,7..▀My.. ...
  711. 000070    14 00 00 00 5C E1 A1 2C   90 54 2D 5A 86 62 00 00    ....\ßí,ÉT-Zåb..
  712. 000080    20 06 00 00 15 00 00 00   39 2E A2 2C 70 6F 1A 8B     .......9.ó,po.ï
  713. 000090    46 FF 00 00 20 07 00 00   16 00 00 00 D0 7B A8 2C    F .. .......╨{¿,
  714. 0000A0    2E DF 1A 8B 4D 79 00 00   20 08 00 00 17 00 00 00    .▀.ïMy.. .......
  715. 0000B0    FF 7B A8 2C B4 D9 35 7C   23 B1 00 00 20 09 00 00     {¿,┤┘5|#▒.. ...
  716. 0000C0    18 00 00 00 CE D4 BA 2C   36 4F BC D8 B2 E7 00 00    ....╬╘║,6O╝╪▓τ..
  717. 0000D0    20 0A 00 00 19 00 00 00   14 5F C3 2C BA A8 4E B0     ........_├,║¿N░
  718. 0000E0    67 76 00 00 20 0B 00 00   1A 00 00 00 6F 89 C3 2C    gv.. .......oë├,
  719. 0000F0    36 4F 0C 01 19 9C 00 00   20 0C 00 00 1B 00 00 00    6O...£.. .......
  720. 000100    F8 30 C6 2C 36 4F FA 48   0E 55 00 00 20 0D 00 00    °0╞,6O·H.U.. ...
  721. 000110    1C 00 00 00 6A 94 D3 2C   36 4F F1 CE CF A2 00 00    ....jö╙,6O±╬╧ó..
  722. 000120    20 0E 00 00 1D 00 00 00   53 DB D5 2C 8D A6 21 CE     .......S█╒,ìª!╬
  723. 000130    F7 AB 00 00 20 0F 00 00   1E 00 00 00 31 29 DC 2C    ≈½.. .......1)▄,
  724.  
  725.  
  726. Field descriptions:
  727. ------------------
  728. To:
  729. The 'To' field is the CRC-16 of the name of the intended recipient agent of
  730. this message or the intended recipient's user number. If the CRC is stored, the
  731. text must be converted to lower case (A-Z changed to a-z) before the CRC is
  732. calculated. If the message is forwarded to another agent, the original or new
  733. index record must be changed to contain the CRC-16 of the new recipient name or
  734. user number.
  735.  
  736. From:
  737. This field, similar to the 'To' field, contains the CRC-16 of the name or
  738. the sending agent of this message or the sender's user number. If the CRC
  739. is stored, the text be converted to lower case (A-Z changed to a-z) before the
  740. CRC is calculated. If the message is forwarded to another agent, the original
  741. or new index record must be changed to contain the CRC-16 of the new sender
  742. name or user number.
  743.  
  744. Subj:
  745. The 'Subj' field contains the CRC-16 of the message's subject. The subject
  746. must be converted to lower case (A-Z changed to a-z) and all preceeding
  747. "re: "'s and "re:"'s removed before calculating the CRC-16.
  748.  
  749. Attr:
  750. This field is a ushort bit-map of the specific attributes for this message.
  751. It is a clone of the 'attr' element of the smbhdr_t structure.
  752.  
  753. Offset:
  754. This ulong is the offset (in bytes) in the header file for this message's
  755. header record.
  756.  
  757. Number:
  758. This ulong is the serial number of this message. Valid values are 1 through
  759. 0xffffffff. No two index records in the same message base may have the same
  760. message number.
  761.  
  762. Time:
  763. This field is the date/time stamp the message was imported to or posted in
  764. the message base. It is a clone of the 'when_imported.time' element of the
  765. smbhdr_t structure.
  766.  
  767. Header File (*.SHD)
  768. ===================
  769. &&Header File (*.SHD) Format
  770. $$SHD_FORM
  771.  
  772. Each SMB header file is made up of two distinct sections: base header records
  773. and message header records.
  774.  
  775. Base Header Records:
  776. -------------------
  777. Base header records are blocks of data that apply to the entire message base
  778. and are of variable length. This specification defines only one base header
  779. record, the "Status info" (smbstatus_t) record. This status info record must be
  780. the first base header record in the file and must be modified if additional
  781. base header records are added.
  782.  
  783. Additional header records allow other developers to store configuration and
  784. status information particular to their application needs. It also allows for
  785. future header record definitions as part of this specification without causing
  786. backward compatibility issues.
  787.  
  788. Each base header record contains a fixed length portion (smbhdr_t) and an
  789. optional variable length portion.
  790.  
  791. Whenever a base header record is read or updated (written), it must first
  792. be successfully locked and subsequently unlocked.
  793.  
  794.  
  795. Message Header Records:
  796. ----------------------
  797. Following the last base header record is the first message header record. Each
  798. header record is stored in one or more 256 byte blocks. There must be exactly
  799. one active message header record for every index record in the index file.
  800. (Note: This does not include deleted message headers that have not been
  801. overwritten by a new message header).
  802.  
  803. Each message header record contains a fixed length portion (msghdr_t), a list
  804. of zero or more fixed length data fields (dfield_t), and a list of three or
  805. more variable length header fields (hfield_t).
  806.  
  807. The value of the data stored in the zero or more unused bytes of the last
  808. header record block have an undefined value, though whenever possible
  809. developers should initialize to binary zero for human readability.
  810.  
  811. Whenever a message header record is read or updated (written), it must first
  812. be successfully locked and subsequently unlocked.
  813.  
  814. Base Header Record (Fixed Portion):
  815. ----------------------------------
  816. C example:
  817.  
  818. typedef struct {
  819.  
  820.     uchar   id[4];          // text or binary unique hdr ID
  821.     ushort  version;        // version number (initially 100h for 1.00)
  822.     ushort  length;         // length including this struct
  823.  
  824.     } smbhdr_t;
  825.  
  826. Base Header #1 (Status info) Record (Variable Portion):
  827. ------------------------------------------------------
  828. C example:
  829.  
  830. typedef struct {
  831.  
  832.     ulong   last_msg;       // last message number
  833.     ulong   total_msgs;     // total messages
  834.     ulong   header_offset;  // byte offset to first header record
  835.     ulong   max_crcs;       // Maximum number of CRCs to keep in history
  836.     ulong   max_msgs;       // Maximum number of messages to keep in base
  837.     ushort  max_age;        // Maximum age of messages (days) to keep in base
  838.     ushort  reserved;       // Reserved for future use
  839.  
  840.     } smbstatus_t;
  841.  
  842.  
  843. Base Header #1 (Status info) Record Contents:
  844. --------------------------------------------
  845. smbhdr.id="SMB\x1a";        // SMB^Z
  846. smbhdr.version=0x110;       // v1.10
  847. smbhdr.length=sizeof(smbhdr_t)+sizeof(smbstatus_t);
  848. smbstatus_t status;
  849.  
  850.  
  851. Additional Base Headers:
  852. -----------------------
  853. Additional headers from developers must have initial 8 bytes in smbhdr_t
  854. format, length must include size of smbhdr_t, and header_offset of smbstatus_t
  855. must be changed to include the size of the additional header(s).
  856.  
  857.  
  858. Example file dump (base header portion only):
  859. --------------------------------------------
  860. 000000    53 4D 42 1A 10 01 20 00   F4 01 00 00 F4 01 00 00    SMB... .⌠...⌠...
  861. 000010    20 00 00 00 D0 07 00 00   D0 07 00 00 00 00 00 00     ...╨...╨.......
  862.  
  863.  
  864. Message Header Record (Fixed portion):
  865. -------------------------------------
  866. C example:
  867.  
  868. typedef struct {
  869.  
  870.     uchar   id[4];          // SHD^Z (same for all types and versions)
  871.     ushort  type;           // Message type (this is the definition of type 0)
  872.     ushort  version;        // Version of type (initially 100h for 1.00)
  873.     ushort  length;         // Total length of fixed portion + all fields
  874.     ushort  attr;           // Attributes (bit field) (duplicated in SID)
  875.     ulong   auxattr;        // Auxillary attributes (bit field)
  876.     ulong   netattr;        // Network attributes (bit field)
  877.     when_t  when_written;   // Date/Time message was originally created
  878.     when_t  when_imported;  // Date/Time message was imported (locally)
  879.     ulong   number;         // Message number (unique, not necessarily seq.)
  880.     ulong   thread_orig;    // Original message number in thread
  881.     ulong   thread_next;    // Next message in thread
  882.     ulong   thread_first;   // Number of first reply to this message
  883.     uchar   reserved[16];   // 16 reserved bytes for future use
  884.     ulong   offset;         // Offset for buffer into data file (0 or mod 256)
  885.     ushort  total_dfields;  // Total number of data fields
  886.  
  887.     } msghdr_t;
  888.  
  889. typedef struct {
  890.  
  891.     ushort  type;           // See "Data Field Types" values
  892.     ulong   offset;         // Offset into buffer 
  893.     ulong   length;         // Length of data field in buffer
  894.  
  895.     } dfield_t;
  896.  
  897. typedef struct {
  898.  
  899.     ushort  type;           // See "Header Field Types" for values
  900.     ushort  length;         // Length of buffer
  901.     uchar   dat[length];
  902.  
  903.     } hfield_t;
  904.  
  905. Example file dump (one header record, both fixed and variable length portions):
  906. ------------------------------------------------------------------------------
  907. 000020    53 48 44 1A 00 00 10 01   F5 00 00 00 00 00 00 00    SHD.....⌡.......
  908. 000030    00 00 00 00 46 DB F7 2C   00 00 7D D7 29 2D 00 00    ....F█≈,..}╫)-..
  909. 000040    01 00 00 00 00 00 00 00   00 00 00 00 00 00 00 00    ................
  910. 000050    00 00 00 00 00 00 00 00   00 00 00 00 00 00 00 00    ................
  911. 000060    00 00 00 00 02 00 00 00   00 00 00 00 4A 01 00 00    ............J...
  912. 000070    02 00 4A 01 00 00 53 00   00 00 00 00 13 00 4D 61    ..J...S.......Ma
  913. 000080    72 69 61 6E 6E 65 20 4D   6F 6E 74 67 6F 6D 65 72    rianne Montgomer
  914. 000090    79 30 00 0C 00 43 61 72   6F 6C 20 47 61 69 73 65    y0...Carol Gaise
  915. 0000A0    72 60 00 07 00 46 61 72   6E 68 61 6D A4 00 14 00    r`...Farnhamñ...
  916. 0000B0    31 3A 31 33 38 2F 31 30   32 2E 30 20 32 63 66 38    1:138/102.0 2cf8
  917. 0000C0    30 35 37 36 A5 00 14 00   31 3A 33 34 33 2F 31 30    0576Ñ...1:343/10
  918. 0000D0    30 2E 30 20 32 63 66 33   62 39 30 61 A3 00 23 00    0.0 2cf3b90aú.#.
  919. 0000E0    31 33 38 2F 31 30 32 20   31 20 32 37 30 2F 31 30    138/102 1 270/10
  920. 0000F0    31 20 32 30 39 2F 32 30   39 20 31 30 33 2F 30 20    1 209/209 103/0 
  921. 000100    33 35 35 02 00 02 00 02   00 03 00 08 00 01 00 8A    355............è
  922. 000110    00 66 00 00 00 00 00 00   00 00 00 00 00 00 00 00    .f..............
  923.  
  924. Contents of example header:
  925. --------------------------
  926. id                   SHD^Z
  927. type                 0000h
  928. version              0110h
  929. length               245
  930. attr                 0000h
  931. auxattr              00000000h
  932. netattr              00000000h
  933. when_written         Sat Nov 27 17:57:10 1993
  934. when_imported        Tue Jan 04 15:54:21 1994
  935. number               1
  936. thread_orig          0
  937. thread_next          0
  938. thread_first         0
  939. reserved[16]         
  940. offset               0
  941. total_dfields        2
  942.  
  943. dfield[0].type       00h
  944. dfield[0].offset     0
  945. dfield[0].length     330
  946. dfield[1].type       02h
  947. dfield[1].offset     330
  948. dfield[1].length     83
  949.  
  950. hfield[0].type       00h
  951. hfield[0].length     19
  952. hfield[0]_dat        Marianne Montgomery
  953. hfield[1].type       30h
  954. hfield[1].length     12
  955. hfield[1]_dat        Carol Gaiser
  956. hfield[2].type       60h
  957. hfield[2].length     7
  958. hfield[2]_dat        Farnham
  959. hfield[3].type       A4h
  960. hfield[3].length     20
  961. hfield[3]_dat        1:138/102.0 2cf80576
  962. hfield[4].type       A5h
  963. hfield[4].length     20
  964. hfield[4]_dat        1:343/100.0 2cf3b90a
  965. hfield[5].type       A3h
  966. hfield[5].length     35
  967. hfield[5]_dat        138/102 1 270/101 209/209 103/0 355
  968. hfield[6].type       02h
  969. hfield[6].length     2
  970. hfield[6]_dat        02 00
  971. hfield[7].type       03h
  972. hfield[7].length     8
  973. hfield[7]_dat        01 00 8A 00 66 00 00 00
  974.  
  975. Fixed Portion Field descriptions:
  976. --------------------------------
  977. Id:
  978. This field (regardless of the header type or version) must always contain the
  979. the string "SHD^Z". This is to aid in the restoration of a corrupted header
  980. file and give a visual indication of the beginning of a new header record when
  981. viewing hex/ASCII dumps of the header file.
  982.  
  983. Type:
  984. This is the message header type. Only one type is currently defined by this
  985. specification (type 0). Any and all future header types will have the first
  986. 4 fields (10 bytes) in the same format of type 0. This allows other types
  987. (with different lengths) to be skipped because the 4th field (length) will
  988. always be in the same position.
  989.  
  990. Version:
  991. This is the version of this header type. This specification defines version
  992. 1.10 of message header type 0 (stored as 110h).
  993.  
  994. Length:
  995. This is the total length of this message header record (including both fixed
  996. and variable length portions, but NOT including unused block space).
  997.  
  998. Attr:
  999. This is a bit field (16-bit) containing basic message attributes (flags) for
  1000. this message. An exact duplicate of this field is stored in the index file as
  1001. well. They must always match.
  1002.  
  1003. Auxattr:
  1004. This is a bit field (32-bit) containing the auxillary attributes (flags) for
  1005. this message. The attributes stored in this variable are more specific in
  1006. nature and less critical than those in the Attr field.
  1007.  
  1008. Netattr:
  1009. This is a bit field (32-bit) containing the network attributes (flags) for this
  1010. message. The attributes stored in this variable are related solely to message
  1011. networking.
  1012.  
  1013. When_written:
  1014. This is the date and time when the message was originally created.
  1015.  
  1016. When_imported:
  1017. This is the date and time when the message was posted on or imported into the
  1018. local message system.
  1019.  
  1020. Number:
  1021. This is the message's unique serial number (from 1 to FFFFFFFFh). This field
  1022. is duplicated in the index file. They must always match.
  1023.  
  1024. Thread_orig:
  1025. If this message is a reply, then this field contains the number of the original
  1026. message that was replied to. If this message was not a reply, this field will
  1027. contain the value 0.
  1028.  
  1029. Thread_next:
  1030. If this message is a reply, and there are later replies to that message
  1031. (the message number contained in the Thread_orig field), then this field will
  1032. contain the number of the next reply in the chain. If this message is the only
  1033. reply to the orignal message, this field will contain the value 0.
  1034.  
  1035. Thread_first:
  1036. If there are any replies to this message (after it has been posted), this field
  1037. will contain the number of the first reply to this message. If there are no
  1038. replies to this message, this field will contain the value 0.
  1039.  
  1040. Reserved:
  1041. Unused bytes, reserved for future definition in the message header type 0
  1042. specification.
  1043.  
  1044. Offset:
  1045. The byte offset into the data file, specifying the start of the buffer for
  1046. all data associated with this message. This value must be either 0 or modula
  1047. 256. When retrieving the actual data portion of data fields, the physical
  1048. offset into the file will be the offset of the message data buffer (this field)
  1049. plus the offset of the individual data field (msghdr_t.offset+dfield_t.offset).
  1050.  
  1051. Total_dfields:
  1052. This field contains the total number of data fields associated with this
  1053. message. The value of this field must match the actual number of data fields
  1054. stored in the header (dfield_t data types following the fixed portion of the
  1055. message header).
  1056.  
  1057.  
  1058. Variable Portion Field descriptions:
  1059. -----------------------------------
  1060. See the Header Field Type and Data Field Type sections for the descriptions
  1061. of the values contained in these fields.
  1062.  
  1063. Message Header Block Allocation (*.SHA)
  1064. =======================================
  1065. &&Header Allocation File (*.SHA) Format
  1066. $$SHA_FORM
  1067.  
  1068. This file contains no header or signature data. Each byte (uchar) in the file
  1069. specifies the allocation state of the corresponding 256 byte block in the
  1070. header (*.SHD) file. A value of 0 indicates a free header block, and a value of
  1071. 1 indicates an allocated block. Other non-zero values are undefined.
  1072.  
  1073. This file must always be opened DENY ALL (non-shareable).
  1074.  
  1075. Message Data (*.SDT)
  1076. ====================
  1077. &&Data File (*.SDT) Format
  1078. $$SDT_FORM
  1079.  
  1080. This file contains no header or signature data. It contains the text and other
  1081. embedded data for the messages in a single message base. The data for each
  1082. message always begins on a 256 byte block boundary. The data in the unused
  1083. portion of a data block is undefined, but should be initialized to NULL
  1084. whenever possible.
  1085.  
  1086. This file must always be opened DENY NONE (shareable).
  1087.  
  1088. Data fields of type TEXT_BODY and TEXT_TAIL must have all trailing white space
  1089. and control characters removed (i.e. the last character of the data record
  1090. must be in the range 21h to FFh). The only exception to this rule, is if the
  1091. TEXT_BODY is terminated with multiple contiguous CRLFs, only the last CRLF
  1092. should be removed. A CRLF should always be appended to the text data when it is
  1093. displayed.
  1094.  
  1095. Message Data Block Allocation (*.SDA)
  1096. =====================================
  1097. &&Data Allocation File (*.SDA) Format
  1098. $$SDA_FORM
  1099.  
  1100. This file contains no header or signature data. Each word (ushort) in the file
  1101. specifies the allocation state of the corresponding 256 byte block in the data
  1102. (*.SDT) file. A value of 0 indicates a free block, and a non-zero value
  1103. indicates the number of message header records associated with this message
  1104. data (most often 1). Each block can be used by up to 65,535 header records.
  1105.  
  1106. This file must always be opened DENY ALL (non-shareable).
  1107.  
  1108. CRC history for duplicate message checking (*.SCH)
  1109. ==================================================
  1110. &&CRC History File (*.SCH) Format
  1111. $$SCH_FORM
  1112.  
  1113. This file is optional and contains no header or signature data. Each long word
  1114. (ulong) in the file contains a CRC-32 of previously posted/imported messages.
  1115. These CRCs can be used to check a candidate message for posting/import to be
  1116. sure the message isn't a duplicate created by human or program error. The
  1117. maximum number of CRCs to store is defined in the first message base header
  1118. record (smbstatus_t.max_crcs).
  1119.  
  1120. This file must always be opened DENY ALL (non-shareable).
  1121.  
  1122. Header Field Types:
  1123. ==================
  1124. &&Header Field Types
  1125. $$HFIELD_T
  1126.  
  1127. These are the defined valid values for hfield_t.type:
  1128.  
  1129. Name     : SENDER
  1130. Value    : 00h
  1131. Data     : ASCII
  1132. Multiple : Yes, order significant
  1133. Required : Yes
  1134. Summary  : Name of agent that sent this message
  1135.  
  1136. If blank (0 length or nulstr), assumed "Anonymous". If multiple SENDER fields
  1137. exist, then the message has been forwarded and the order of the fields in the
  1138. record must match the forwarding order (chronologically). When forwarding a
  1139. message, the original SENDER field should be left intact and new SENDER,
  1140. FORWARDED, and RECIPIENT fields added to the end of the record.
  1141.  
  1142.  
  1143. Name     : SENDERAGENT
  1144. Value    : 01h
  1145. Data     : ushort
  1146. Multiple : Yes, order significant
  1147. Required : No
  1148. Default  : AGENT_PERSON or previous SENDERAGENT if exists
  1149. Summary  : Type of agent that sent this message
  1150.  
  1151. If multiple SENDER fields exist, then the message has been forwarded. If any of the
  1152. forwarding agents is of a type other than AGENT_PERSON, then this field must
  1153. follow that SENDER field to specify the agent type.
  1154.  
  1155. Name     : SENDERNETTYPE
  1156. Value    : 02h
  1157. Data     : ushort
  1158. Multiple : Yes, order significant
  1159. Required : No
  1160. Default  : NET_NONE or previous SENDERNETTYPE if exists
  1161. Summary  : Type of network message was sent from
  1162.  
  1163. If multiple SENDERNETADDR fields are included, a SENDERNETTYPE field should be
  1164. included before each to determine what data type the address is stored in.
  1165.  
  1166. Name     : SENDERNETADDR
  1167. Value    : 03h
  1168. Data     : undef
  1169. Multiple : Yes, order significant
  1170. Required : No
  1171. Default  : Previous SENDERNETADDR if exists
  1172. Summary  : Network address for agent that sent this message
  1173.  
  1174. The SENDERNETTYPE field indicates the data type of this field. If the
  1175. SENDERNETTYPE is of type NET_INTERNET, the local-part of the Internet
  1176. address is optional. If the local-part separator character ('@') is omitted,
  1177. the SENDER field is assumed to be the local-part of the address.
  1178.  
  1179. Name     : SENDEREXT
  1180. Value    : 04h
  1181. Data     : ASCII
  1182. Multiple : Yes, order significant
  1183. Required : No
  1184. Default  : Previous SENDEREXT if exists
  1185. Summary  : Extension of sending agent
  1186.  
  1187. This field is useful for storing the sending agent's extension, when the
  1188. agent's extension binds more tightly than the agent's name.
  1189.  
  1190. For example, Synchronet Multinode BBS Software stores local e-mail with the
  1191. sending and receiving agent's user numbers stored as their respective
  1192. extensions. This is done so that if a user name changes for some reason,
  1193. messages will not "disappear" from the users's mail box. In Synchronet local
  1194. e-mail, user numbers bind more tightly than user names.
  1195.  
  1196. If the SENDEREXT field is specified, then the "From" field in the index must
  1197. contain the CRC-16 of this field rather than the SENDER (name) field.
  1198.  
  1199. Name     : SENDERPOS
  1200. Value    : 05h
  1201. Data     : ASCII
  1202. Multiple : Yes, order significant
  1203. Required : No
  1204. Default  : Previous SENDERPOS if exists
  1205. Summary  : Position of sending agent
  1206.  
  1207. Primarily for documentary purposes, this field contains the position of the
  1208. sending agent (i.e. President, Sysop, C.E.O., MIS Director, etc).
  1209.  
  1210. It can also be useful for getting a message or reply to the intended
  1211. recipient when the agent name is not located or is unknown, but the position
  1212. of the agent is known and specified.
  1213.  
  1214. Name     : SENDERORG
  1215. Value    : 06h
  1216. Data     : ASCII
  1217. Multiple : Yes, order significant
  1218. Required : No
  1219. Default  : Previous SENDERORG if exists
  1220. Summary  : Organization name of sending agent
  1221.  
  1222. Primarily for documentary purposes, this field contains the organization to
  1223. which the sending agent belongs (i.e. Microsoft, Joe's BBS, SoCal User's Group,
  1224. etc).
  1225.  
  1226. Name     : AUTHOR
  1227. Value    : 10h
  1228. Data     : ASCII
  1229. Multiple : Yes
  1230. Required : No
  1231. Default  : First SENDER
  1232. Summary  : Name of agent that created this message
  1233.  
  1234. This field can only be added by the process that originally creates the
  1235. message. It should not be included if same as first SENDER field. If multiple
  1236. AUTHOR fields exist, then the message was created by multiple agents and is
  1237. considered valid. The order of multiple AUTHOR fields in the record is not
  1238. significant.
  1239.  
  1240. Name     : AUTHORAGENT
  1241. Value    : 11h
  1242. Data     : ushort
  1243. Multiple : Yes, order significant
  1244. Required : No
  1245. Default  : SENDERAGENT or previous AUTHORAGENT if exists
  1246. Summary  : Type of agent that created this message
  1247.  
  1248. This field can only be added by the process that originally creates the
  1249. message. It should not be included if same as first SENDERAGENT field. If
  1250. multiple AUTHOR fields exist, then the message was created by multiple agents
  1251. and if the agent type for any of the authors is other than AGENT_PERSON, an
  1252. AUTHORAGENT field must follow to specify the agent type.
  1253.  
  1254. Name     : AUTHORNETTYPE
  1255. Value    : 12h
  1256. Data     : ushort
  1257. Multiple : Yes, order significant
  1258. Required : No
  1259. Default  : SENDERNETTYPE or previous AUTHORNETTYPE if exists
  1260. Summary  : Type of network this author is member of
  1261.  
  1262. Name     : AUTHORNETADDR
  1263. Value    : 13h
  1264. Data     : undef
  1265. Multiple : Yes, order significant
  1266. Required : No
  1267. Default  : SENDERNETADDR or previous AUTHORNETADDR if exists
  1268. Summary  : Network address of this author
  1269.  
  1270. Name     : AUTHOREXT
  1271. Value    : 14h
  1272. Data     : ASCII
  1273. Multiple : Yes, order significant
  1274. Required : No
  1275. Default  : SENDEREXT or previous AUTHOREXT if exists
  1276. Summary  : Extension of this author
  1277.  
  1278. Name     : AUTHORPOS
  1279. Value    : 15h
  1280. Data     : ASCII
  1281. Multiple : Yes, order significant
  1282. Required : No
  1283. Default  : SENDERPOS or previous AUTHORPOS if exists
  1284. Summary  : Position of this author
  1285.  
  1286. Name     : AUTHORORG
  1287. Value    : 16h
  1288. Data     : ASCII
  1289. Multiple : Yes, order significant
  1290. Required : No
  1291. Default  : SENDERORG or previous AUTHORORG if exists
  1292. Summary  : Organization this author belongs to
  1293.  
  1294. Name     : REPLYTO
  1295. Value    : 20h
  1296. Data     : ASCII
  1297. Multiple : Yes, but only last is valid
  1298. Required : No
  1299. Default  : SENDER
  1300. Summary  : Name of agent that replies should go to
  1301.  
  1302. Name     : REPLYTOAGENT
  1303. Value    : 21h
  1304. Data     : ushort
  1305. Multiple : Yes, but only last is valid
  1306. Required : No
  1307. Default  : SENDERAGENT
  1308. Summary  : Type of agent that replies should go to
  1309.  
  1310. Name     : REPLYTONETTYPE
  1311. Value    : 22h
  1312. Data     : ushort
  1313. Multiple : Yes, but only last is valid
  1314. Required : No
  1315. Default  : SENDERNETTYPE
  1316. Summary  : Type of network that replies should go to
  1317.  
  1318. Name     : REPLYTONETADDR
  1319. Value    : 23h
  1320. Data     : undef
  1321. Multiple : Yes, but only last is valid
  1322. Required : No
  1323. Default  : SENDERNETADDR
  1324. Summary  : Network address that replies should go to
  1325.  
  1326. Name     : REPLYTOEXT
  1327. Value    : 24h
  1328. Data     : ASCII
  1329. Multiple : Yes, but only last is valid
  1330. Required : No
  1331. Default  : SENDEREXT
  1332. Summary  : Extension of agent that replies should go to
  1333.  
  1334. Name     : REPLYTOPOS
  1335. Value    : 25h
  1336. Data     : ASCII
  1337. Multiple : Yes, but only last is valid
  1338. Required : No
  1339. Default  : SENDERPOS
  1340. Summary  : Position of agent that replies should go to
  1341.  
  1342. Name     : REPLYTOORG
  1343. Value    : 26h
  1344. Data     : ASCII
  1345. Multiple : Yes, but only last is valid
  1346. Required : No
  1347. Default  : SENDERORG
  1348. Summary  : Organization of agent that replies should go to
  1349.  
  1350. Name     : RECIPIENT
  1351. Value    : 30h
  1352. Data     : ASCII
  1353. Multiple : Yes, order significant
  1354. Required : Yes
  1355. Default  : "All"
  1356. Summary  : Name of agent to receive this message
  1357.  
  1358. If multiple RECIPIENT fields exist, the message has been forwarded and for each
  1359. additional RECIPIENT field (after the initial RECIPIENT), there should be a
  1360. FORWARDED field. The order of the RECIPIENT fields in the record must match the
  1361. order in which the message was sent and forwarded (chronologically).
  1362.  
  1363. Name     : RECIPIENTAGENT
  1364. Value    : 31h
  1365. Data     : ushort
  1366. Multiple : Yes, order significant
  1367. Required : No
  1368. Default  : AGENT_PERSON or previous RECIPIENTAGENT if exists
  1369. Summary  : Type of agent to receive this message
  1370.  
  1371. If multiple RECIPIENT fields exist, the message has been forwarded. If any of
  1372. the recipient agents are of a type other than AGENT_PERSON, this field must
  1373. follow the RECIPIENT field to specify the agent type.
  1374.  
  1375. Name     : RECIPIENTNETTYPE
  1376. Value    : 32h
  1377. Data     : ushort
  1378. Multiple : Yes, order significant
  1379. Required : No
  1380. Default  : NET_NONE or previous RECIPIENTNETTYPE if exists
  1381. Summary  : Type of network to receive this message
  1382.  
  1383. Name     : RECIPIENTNETADDR
  1384. Value    : 33h
  1385. Data     : undef
  1386. Multiple : Yes, order significant
  1387. Required : No
  1388. Default  : Previous RECIPIENTNETADDR if exists
  1389. Summary  : Address of network to receive this message
  1390.  
  1391. Name     : RECIPIENTEXT
  1392. Value    : 34h
  1393. Data     : ASCII
  1394. Multiple : Yes, order significant
  1395. Required : No
  1396. Default  : Previous RECIPIENTEXT if exists
  1397. Summary  : Extension of agent to receive this message
  1398.  
  1399. If the RECIPIENTEXT field is specified, then the "To" field in the index must
  1400. contain the CRC-16 of this field rather than the RECIPIENT (name) field.
  1401.  
  1402. Name     : RECIPIENTPOS
  1403. Value    : 35h
  1404. Data     : ASCII
  1405. Multiple : Yes, order significant
  1406. Required : No
  1407. Default  : Previous RECIPIENTPOS if exists
  1408. Summary  : Position of agent to receive this message
  1409.  
  1410. Name     : RECIPIENTORG
  1411. Value    : 36h
  1412. Data     : ASCII
  1413. Multiple : Yes, order significant
  1414. Required : No
  1415. Default  : Previous RECIPIENTORG if exists
  1416. Summary  : Type of agent to receive this message
  1417.  
  1418. Name     : FORWARDTO
  1419. Value    : 40h
  1420. Data     : ASCII
  1421. Multiple : Yes, order significant
  1422. Required : No
  1423. Summary  : Name of agent this message is to be forwarded to
  1424.  
  1425. Name     : FORWARDTOAGENT
  1426. Value    : 41h
  1427. Data     : ushort
  1428. Multiple : Yes, order significant
  1429. Required : No
  1430. Default  : RECIPIENTAGENT or previous FORWARDTOAGENT if exists
  1431. Summary  : Type of agent this message is to be forwarded to
  1432.  
  1433. Name     : FORWARDTONETTYPE
  1434. Value    : 42h
  1435. Data     : ushort
  1436. Multiple : Yes, order significant
  1437. Required : No
  1438. Default  : RECIPIENTNETTYPE or previous FORWARDTONETTYPE if exists
  1439. Summary  : Type of network this message is to be forwarded to
  1440.  
  1441. Name     : FORWARDTONETADDR
  1442. Value    : 43h
  1443. Data     : undef
  1444. Multiple : Yes, order significant
  1445. Required : No
  1446. Default  : RECIPIENTNETADDR or previous FORWARDTONETADDR if exists
  1447. Summary  : Network address this message is to be forwarded to
  1448.  
  1449. Name     : FORWARDTOEXT
  1450. Value    : 44h
  1451. Data     : ASCII
  1452. Multiple : Yes, order significant
  1453. Required : No
  1454. Default  : RECIPIENTEXT or previous FORWARDTOEXT if exists
  1455. Summary  : Extension of agent this message is to be forwarded to
  1456.  
  1457. Name     : FORWARDTOPOS
  1458. Value    : 45h
  1459. Data     : ASCII
  1460. Multiple : Yes, order significant
  1461. Required : No
  1462. Default  : RECIPIENTPOS or previous FORWARDTOPOS if exists
  1463. Summary  : Position of agent this message is to be forwarded to
  1464.  
  1465. Name     : FORWARDTOORG
  1466. Value    : 46h
  1467. Data     : ASCII
  1468. Multiple : Yes, order significant
  1469. Required : No
  1470. Default  : RECIPIENTORG or previous FORWARDTOORG if exists
  1471. Summary  : Organization of agent this message is to be forwarded to
  1472.  
  1473. Name     : FORWARDED
  1474. Value    : 48h
  1475. Data     : when_t
  1476. Multiple : Yes, order significant
  1477. Required : Yes, if forwarded
  1478. Summary  : Date/Time this message was forwarded to another agent
  1479.  
  1480. Name     : RECEIVEDBY
  1481. Value    : 50h
  1482. Data     : ASCII
  1483. Multiple : Yes, order significant
  1484. Required : Yes, if receiving agent is other than RECIPIENT
  1485. Summary  : Name of agent that received this message
  1486.  
  1487. Name     : RECEIVEDBYAGENT
  1488. Value    : 51h
  1489. Data     : ushort
  1490. Multiple : Yes, order significant
  1491. Required : No
  1492. Default  : RECIPIENTAGENT or previous RECEIVEDBYAGENT if exists
  1493. Summary  : Type of agent that received this message
  1494.  
  1495. Name     : RECEIVEDBYNETTYPE
  1496. Value    : 52h
  1497. Data     : ushort
  1498. Multiple : Yes, order significant
  1499. Required : No
  1500. Default  : RECIPIENTNETTYPE or previous RECEIVEDBYNETTYPE if exists
  1501. Summary  : Type of network that received this message
  1502.  
  1503. Name     : RECEIVEDBYNETADDR
  1504. Value    : 53h
  1505. Data     : undef
  1506. Multiple : Yes, order significant
  1507. Required : No
  1508. Default  : RECIPIENTNETADDR or previous RECEIVEDBYNETADDR if exists
  1509. Summary  : Network address that received this message
  1510.  
  1511. Name     : RECEIVEDBYEXT
  1512. Value    : 54h
  1513. Data     : ASCII
  1514. Multiple : Yes, order significant
  1515. Required : No
  1516. Default  : RECIPIENTEXT or previous RECEIVEDBYEXT if exists
  1517. Summary  : Extension of agent that received this message
  1518.  
  1519. Name     : RECEIVEDBYPOS
  1520. Value    : 55h
  1521. Data     : ASCII
  1522. Multiple : Yes, order significant
  1523. Required : No
  1524. Default  : RECIPIENTPOS or previous RECEIVEDBYPOS if exists
  1525. Summary  : Position of agent that received this message
  1526.  
  1527. Name     : RECEIVEDBYORG
  1528. Value    : 56h
  1529. Data     : ASCII
  1530. Multiple : Yes, order significant
  1531. Required : No
  1532. Default  : RECIPIENTORG or previous RECEIVEDBYORG if exists
  1533. Summary  : Organization of agent that received this message
  1534.  
  1535. Name     : RECEIVED
  1536. Value    : 58h
  1537. Data     : when_t
  1538. Multiple : Yes, order significant
  1539. Required : Yes, if received
  1540. Default  : NULL
  1541. Summary  : Date/Time this message was received
  1542.  
  1543. Name     : SUBJECT
  1544. Value    : 60h
  1545. Data     : ASCII
  1546. Multiple : No
  1547. Required : Yes, but may be blank (0 length or nulstr)
  1548. Summary  : Subject/title of message
  1549.  
  1550. Name     : SUMMARY
  1551. Value    : 61h
  1552. Data     : ASCII
  1553. Multiple : No
  1554. Required : No
  1555. Summary  : Summary of message contents, created by AUTHOR
  1556.  
  1557. Name     : COMMENT
  1558. Value    : 62h
  1559. Data     : ASCII
  1560. Multiple : Yes
  1561. Required : No
  1562. Summary  : Comment about this message, created by SENDER
  1563.  
  1564. This field is useful for adding notes to a message when forwarding to a new
  1565. recipient.
  1566.  
  1567. Name     : CARBONCOPY
  1568. Value    : 63h
  1569. Data     : ASCII
  1570. Multiple : Yes
  1571. Required : No
  1572. Summary  : List of agents this message was also sent to
  1573.  
  1574. This field is optional and only for the use of notifying the recipient of who
  1575. else received the message.
  1576.  
  1577. Name     : GROUP
  1578. Value    : 64h
  1579. Data     : ASCII
  1580. Multiple : Yes
  1581. Required : No
  1582. Summary  : Name of group of users to receive message on recipient system
  1583.  
  1584. This field is used when sending to a group name across a network, where the
  1585. group can be expanded into multiple header records for each agent on the
  1586. destination system.
  1587.  
  1588. Name     : EXPIRATION
  1589. Value    : 65h
  1590. Data     : when_t
  1591. Multiple : No
  1592. Required : No
  1593. Summary  : Date/Time that this message will expire
  1594.  
  1595. Name     : PRIORITY
  1596. Value    : 66h
  1597. Data     : ulong
  1598. Multiple : No
  1599. Required : No
  1600. Default  : 0
  1601. Summary  : Message priority (0 is lowest, FFFFFFFFh is highest)
  1602.  
  1603. Name     : FILEATTACH
  1604. Value    : 70h
  1605. Data     : ASCII
  1606. Multiple : Yes
  1607. Required : No
  1608. Summary  : Name/file specification of attached file(s)
  1609.  
  1610. Name of attached file(s). Wildcards allowed. MSG_FILEATTACH attribute must be
  1611. set. If the MSG_FILEATTACH attribute is set but this field is not included,
  1612. the SUBJECT field is assumed to be the filename(s).
  1613.  
  1614. Name     : DESTFILE
  1615. Value    : 71h
  1616. Data     : ASCII
  1617. Multiple : Yes, order significant
  1618. Required : No
  1619. Summary  : Destination name for attached file(s)
  1620.  
  1621. Wildcards allowed. FILEATTACH field must also be included.
  1622.  
  1623. Name     : FILEATTACHLIST
  1624. Value    : 72h
  1625. Data     : ASCII
  1626. Multiple : Yes
  1627. Required : No
  1628. Summary  : Name of ASCII list of attached filenames
  1629.  
  1630. Wildcards not allowed in ASCII list filename. Wildcards allowed in ASCII list.
  1631. MSG_FILEATTACH attribute must be set.
  1632.  
  1633. Name     : DESTFILELIST
  1634. Value    : 73h
  1635. Data     : ASCII
  1636. Multiple : Yes, order significant
  1637. Required : No
  1638. Summary  : Name of ASCII list of destination filenames
  1639.  
  1640. Wildcards not allowed in ASCII list filename. Wildcards allowed in ASCII list.
  1641.  
  1642. Name     : FILEREQUEST
  1643. Value    : 74h
  1644. Data     : ASCII
  1645. Multiple : Yes
  1646. Required : No
  1647. Summary  : Name of requested file
  1648.  
  1649. Wildcards allowed. MSG_FILEREQUEST attribute must be set
  1650.  
  1651. Name     : FILEPASSWORD
  1652. Value    : 75h
  1653. Data     : ASCII
  1654. Multiple : Yes, order significant
  1655. Required : No
  1656. Summary  : Password for FILEREQUEST
  1657.  
  1658. Name     : FILEREQUESTLIST
  1659. Value    : 76h
  1660. Data     : ASCII
  1661. Multiple : Yes
  1662. Required : No
  1663. Summary  : Name of ASCII list of filenames to request
  1664.  
  1665. Wildcards allowed.
  1666.  
  1667. Name     : FILEPASSWORDLIST
  1668. Value    : 77h
  1669. Data     : ASCII
  1670. Multiple : Yes, order significant
  1671. Required : No
  1672. Summary  : Name of ASCII list of passwords for FILEREQUESTLIST
  1673.  
  1674. Name     : IMAGEATTACH
  1675. Value    : 80h
  1676. Data     : mattach_t
  1677. Multiple : Yes, order significant
  1678. Required : No
  1679. Summary  : Type and filename of attached image file for display
  1680.  
  1681. MSG_FILEATTACH attribute must be set. See Image Types for valid
  1682. mattach_t.type values.
  1683.  
  1684. Name     : ANIMATTACH
  1685. Value    : 81h
  1686. Data     : mattach_t
  1687. Multiple : Yes, order significant
  1688. Required : No
  1689. Summary  : Type and filename of attached graphical animation file for display
  1690.  
  1691. MSG_FILEATTACH attribute must be set. See Animation Types for valid
  1692. mattach_t.type values.
  1693.  
  1694. Name     : FONTATTACH
  1695. Value    : 82h
  1696. Data     : mattach_t
  1697. Multiple : Yes, order significant
  1698. Required : No
  1699. Summary  : Type and filename of attached font definition file
  1700.  
  1701. MSG_FILEATTACH attribute must be set. See Font Types for valid mattach_t.type
  1702. values.
  1703.  
  1704. Name     : SOUNDATTACH
  1705. Value    : 83h
  1706. Data     : mattach_t
  1707. Multiple : Yes, order significant
  1708. Required : No
  1709. Summary  : Type and filename of attached sound file for playback
  1710.  
  1711. MSG_FILEATTACH attribute must be set. See Sound Types for valid mattach_t.type
  1712. values.
  1713.  
  1714. Name     : PRESENTATTACH
  1715. Value    : 84h
  1716. Data     : mattach_t
  1717. Multiple : Yes, order significant
  1718. Required : No
  1719. Summary  : Type and filename of attached presentation definition file
  1720.  
  1721. MSG_FILEATTACH attribute must be set. See Present Types for valid
  1722. mattach_t.type values.
  1723.  
  1724. Name     : VIDEOATTACH
  1725. Value    : 85h
  1726. Data     : vattach_t
  1727. Multiple : Yes, order significant
  1728. Required : No
  1729. Summary  : Type and filename of attached interleaved video/sound file
  1730.  
  1731. MSG_FILEATTACH attribute must be set. See Video Types for valid
  1732. vattach_t.type values and Video Compression Types for valid vattach_t.comp
  1733. values.
  1734.  
  1735. Name     : APPDATAATTACH
  1736. Value    : 86h
  1737. Data     : mattach_t
  1738. Multiple : Yes, order significant
  1739. Required : No
  1740. Summary  : Name of attached application data file for process/display
  1741.  
  1742. MSG_FILEATTACH attribute must be set. See Application Data Types for valid
  1743. mattach_t.type values.
  1744.  
  1745. Name     : IMAGETRIGGER
  1746. Value    : 90h
  1747. Data     : typestr_t
  1748. Multiple : Yes, order significant
  1749. Required : No
  1750. Summary  : Type and filename of image file to trigger for display
  1751.  
  1752. See Image Types for valid typestr_t.type values.
  1753.  
  1754. Name     : ANIMTRIGGER
  1755. Value    : 91h
  1756. Data     : typestr_t
  1757. Multiple : Yes, order significant
  1758. Required : No
  1759. Summary  : Type and filename of animation file to trigger for display
  1760.  
  1761. See Animation Types for valid typestr_t.type values.
  1762.  
  1763. Name     : FONTTRIGGER
  1764. Value    : 92h
  1765. Data     : typestr_t
  1766. Multiple : Yes, order significant
  1767. Required : No
  1768. Summary  : Type and filename of font definition file to trigger
  1769.  
  1770. See Font Types for valid typestr_t.type values.
  1771.  
  1772. Name     : SOUNDTRIGGER
  1773. Value    : 93h
  1774. Data     : typestr_t
  1775. Multiple : Yes, order significant
  1776. Required : No
  1777. Summary  : Type and filename of sound file to trigger for playback
  1778.  
  1779. See Sound Types for valid typestr_t.type values.
  1780.  
  1781. Name     : PRESENTTRIGGER
  1782. Value    : 94h
  1783. Data     : typestr_t
  1784. Multiple : Yes, order significant
  1785. Required : No
  1786. Summary  : Type and filename of presentation definition file to trigger
  1787.  
  1788. See Present Types for valid typestr_t.type values.
  1789.  
  1790. Name     : VIDEOTRIGGER
  1791. Value    : 95h
  1792. Data     : typestr_t
  1793. Multiple : Yes, order significant
  1794. Required : No
  1795. Summary  : Type and filename of interleaved video/sound file to trigger
  1796.  
  1797. See Video Types for valid typestr_t.type values.
  1798.  
  1799. Name     : APPDATATRIGGER
  1800. Value    : 96h
  1801. Data     : typestr_t
  1802. Multiple : Yes, order significant
  1803. Required : No
  1804. Summary  : Type and filename of application data file to trigger
  1805.  
  1806. See Application Data Types for valid typestr_t.type values.
  1807.  
  1808. Name     : FIDOCTRL
  1809. Value    : A0h
  1810. Data     : ASCII
  1811. Multiple : Yes, order significant
  1812. Required : No
  1813. Format   : keyword ":" [" "] appdata
  1814. Summary  : FTS/FSC-compliant control information line
  1815.  
  1816. Any FidoNet FTS/FSC-compliant control information ("kludge") line that
  1817. does not have an equivalent representation here. All data not unique to the
  1818. actual control line, including leading and trailing white space, Ctrl-A (01h)
  1819. character and terminating CR must be ommited. Defined in FTS-0001.
  1820.  
  1821. Name     : FIDOAREA
  1822. Value    : A1h
  1823. Data     : ASCII
  1824. Multiple : No
  1825. Required : No
  1826. Summary  : FTN EchoMail conference name.
  1827.  
  1828. Defined in FTS-0004.
  1829.  
  1830. Name     : FIDOSEENBY
  1831. Value    : A2h
  1832. Data     : ASCII
  1833. Multiple : Yes, order significant
  1834. Required : No
  1835. Format   : net"/"node [" "[net"/"]node] [...]
  1836. Summary  : Used to store two-dimensional (net/node) SEEN-BY information
  1837.  
  1838. Often used in FTN EchoMail environments. Only the actual SEEN-BY data is stored
  1839. and SEEN-BY: is stripped along with any leading and trailing white space
  1840. characters. Defined in FTS-0004.
  1841.  
  1842. Name     : FIDOPATH
  1843. Value    : A3h
  1844. Data     : ASCII
  1845. Multiple : Yes, order significant
  1846. Required : No
  1847. Format   : net"/"node [" "[net"/"]node] [...]
  1848. Summary  : Used to store two-dimensional (net/node)
  1849.  
  1850. Defined in FTS-0004. ^aPATH: is stripped along with any leading and trailing
  1851. white space characters.
  1852.  
  1853. Name     : FIDOMSGID
  1854. Value    : A4h
  1855. Data     : ASCII
  1856. Multiple : No
  1857. Required : No
  1858. Format   : origaddr " " serialno
  1859. Summary  : MSGID field as specified in FTS-0009.
  1860.  
  1861. Name     : FIDOREPLYID
  1862. Value    : A5h
  1863. Data     : ASCII
  1864. Multiple : No
  1865. Required : No
  1866. Format   : origaddr " " serialno
  1867. Summary  : REPLY field as specified in FTS-0009.
  1868.  
  1869. Name     : FIDOPID
  1870. Value    : A6h
  1871. Data     : ASCII
  1872. Multiple : No
  1873. Required : No
  1874. Format   : pID " " version [" "serialno]
  1875. Summary  : Indentification string of program that created this message
  1876.  
  1877. Defined FSC-0046. "^aPID:" and any white space is not included.
  1878.  
  1879. Name     : FIDOFLAGS
  1880. Value    : A7h
  1881. Data     : ASCII
  1882. Multiple : Yes
  1883. Required : No
  1884. Summary  : Used to store the FTN FLAGS kludge information
  1885.  
  1886. Note that all FLAG options that have binary representation in the message
  1887. header must be removed from the FLAGS string prior to storing it. Only the
  1888. actual flags option string is stored and ^aFLAGS is stripped along with any
  1889. leading and trailing white space characters. Defined in FSC-0053.
  1890.  
  1891. Name     : RFC822HEADER
  1892. Value    : B0h
  1893. Data     : ASCII
  1894. Multiple : Yes, order significant
  1895. Required : No
  1896. Format   : field-name ":" [field-body] [CRLF]
  1897. Summary  : Undefined RFC-822 header field
  1898.  
  1899. Internet Message storage format, that does not have an equivalent
  1900. representation here. Folded header fields are allowed. Terminating CRLF may be
  1901. ommited.
  1902.  
  1903. Name     : RFC822MSGID
  1904. Value    : B1h
  1905. Data     : ASCII
  1906. Multiple : No
  1907. Required : No
  1908. Format   : "<" addr-spec ">"
  1909. Summary  : Message-ID field as specified in RFC-822.
  1910.  
  1911. Name     : RFC822REPLYID
  1912. Value    : B2h
  1913. Data     : ASCII
  1914. Multiple : No
  1915. Required : No
  1916. Format   : "<" addr-spec ">"
  1917. Summary  : In-Reply-To field as specified in RFC-822.
  1918.  
  1919. Name     : UNKNOWN
  1920. Value    : F0h
  1921. Data     : undef
  1922. Multiple : Yes
  1923. Required : No
  1924. Summary  : Undefined header field of undefined type
  1925.  
  1926. This field is useful for retaining binary header fields (that do not have an
  1927. equivalent representation here) between message storage formats.
  1928.  
  1929. Name     : UNKNOWNASCII
  1930. Value    : F1h
  1931. Data     : ASCII
  1932. Multiple : Yes
  1933. Required : No
  1934. Summary  : Undefined header field of type ASCII
  1935.  
  1936. This field is useful for retaining ASCII header fields (that do not have an
  1937. equivalent representation here) between message storage formats.
  1938.  
  1939. Name     : UNUSED
  1940. Value    : FFh
  1941. Data     : undef
  1942. Multiple : Yes
  1943. Required : No
  1944. Summary  : Unused (deleted) header field
  1945.  
  1946. The data contained in this header field is of an unknown type and should not be
  1947. processed.
  1948.  
  1949.  
  1950. Note:
  1951. ----
  1952. Specifically, not defined are the values F000h through FFFFh. These values
  1953. are to be used for user or system defined header fields. Digital Dynamics
  1954. requests that any developers or organizations that wish to have additional
  1955. header fields added to this specification notify Digital Dynamics through any
  1956. of the contact methods listed at the beginning of this document.
  1957.  
  1958. Data Field Types:
  1959. ================
  1960. &&Data Field Types
  1961. $$DFIELD_T
  1962.  
  1963. These are the defined valid values for dfield_t.type:
  1964.  
  1965.  
  1966. Val Name                Data        Description
  1967. --- ----                ----        -----------
  1968. 00h TEXT_BODY           mtext_t     Displayable text (body of message).
  1969.                                     Included in duplicate message checking.
  1970.                                     All terminating white space and control
  1971.                                     characters are to be truncated from data
  1972.                                     (except when multiple contiguous CRLFs
  1973.                                     terminate the text, only the last CRLF
  1974.                                     is removed).
  1975.  
  1976. 01h TEXT_SOUL           mtext_t     Non-displayed text.
  1977.                                     Not normally displayed. Not necessarily
  1978.                                     displayable.
  1979.                                     Included in duplicate message checking.
  1980.  
  1981. 02h TEXT_TAIL           mtext_t     Displayable text (tag/tear/origin lines,
  1982.                                     etc).
  1983.                                     Not included in duplicate message checking.
  1984.                                     All terminating white space and control
  1985.                                     characters are to be truncated from data.
  1986.  
  1987. 03h TEXT_WING           mtext_t     Non-displayed text.
  1988.                                     Not normally displayed. Not necessarily
  1989.                                     displayable.
  1990.                                     Not included in duplicate message checking.
  1991.  
  1992. 10h FTEXT_BODY          ftext_t     Formatted equivalent of TEXT_BODY to be
  1993.                                     displayed in place of TEXT_BODY if format
  1994.                                     is supported. See Image Types for valid
  1995.                                     values of ftext_t.type.
  1996.  
  1997. 12h FTEXT_TAIL          ftext_t     Formatted equivalent of TEXT_TAIL to be
  1998.                                     displayed in place of TEXT_TAIL if format
  1999.                                     is supported. See Image Types for valid
  2000.                                     values of ftext_t.type.
  2001.  
  2002. 20h IMAGEEMBED          membed_t    Type and data of embedded raster image file
  2003.                                     for display.
  2004.                                     See Image Types for valid membed.type
  2005.                                     values.
  2006.  
  2007. 21h ANIMEMBED           membed_t    Type and data of embedded graphical
  2008.                                     animation file for display.
  2009.                                     See Animation Types for valid membed.type
  2010.                                     values.
  2011.  
  2012. 22h FONTEMBED           membed_t    Type and data of embedded font definition
  2013.                                     file. See Font Types for valid
  2014.                                     membed_t.type values.
  2015.  
  2016. 23h SOUNDEMBED          membed_t    Type and data of embedded sound file for
  2017.                                     playback.
  2018.                                     See Sound Types for valid membed_t.type
  2019.                                     values.
  2020.  
  2021. 24h PRESENTEMBED        membed_t    Type and data of embedded presentation
  2022.                                     definition file.
  2023.                                     See Present Types for valid membed_t.type
  2024.                                     values.
  2025.  
  2026. 25h VIDEOEMBED          vembed_t    Type and data of embedded video/sound file
  2027.                                     for playback.
  2028.                                     See Video Types for valid vembed_t.type
  2029.                                     values.
  2030.                                     See Video Compression Types for valid
  2031.                                     vembed_t.comp values.
  2032.  
  2033. 26h APPDATAEMBED        membed_t    Type and data of embedded application data
  2034.                                     file for process/display.
  2035.                                     See Application Data Types for valid
  2036.                                     membed_t.type values.
  2037.  
  2038. FFh UNUSED              undef       Space allocated for future update/expansion
  2039.  
  2040.  
  2041. Specifically, not defined are the values F000h through FFFFh. These values
  2042. are to be used for user or system defined data fields. Digital Dynamics
  2043. requests that any developers or organizations that wish to have additional
  2044. data fields added to this specification notify Digital Dynamics through any
  2045. of the contact methods listed at the beginning of this document.
  2046.  
  2047.  
  2048. Message Attributes:
  2049. ------------------
  2050. &&Message Attributes
  2051. $$ATTRBITS
  2052.  
  2053. These are the bit values for idxrec_t.attr and msghdr_t.attr:
  2054.  
  2055. MSG_PRIVATE         (1<<0)  // Private
  2056. MSG_READ            (1<<1)  // Read by addressee
  2057. MSG_PERMANENT       (1<<2)  // Permanent
  2058. MSG_LOCKED          (1<<3)  // Msg is locked, no editing possible
  2059. MSG_DELETE          (1<<4)  // Msg is marked for deletion
  2060. MSG_ANONYMOUS       (1<<5)  // Anonymous author
  2061. MSG_KILLREAD        (1<<6)  // Delete message after it has been read
  2062. MSG_MODERATED       (1<<7)  // This message must be validated
  2063. MSG_VALIDATED       (1<<8)  // This message has been validated by a moderator
  2064.  
  2065.  
  2066. Auxillary Attributes:
  2067. --------------------
  2068. These are the bit values for msghdr_t.auxattr:
  2069.  
  2070. MSG_FILEREQUEST     (1<<0)  // File request
  2071. MSG_FILEATTACH      (1<<1)  // File(s) attached to Msg
  2072. MSG_TRUNCFILE       (1<<2)  // Truncate file(s) when sent
  2073. MSG_KILLFILE        (1<<3)  // Delete file(s) when sent
  2074. MSG_RECEIPTREQ      (1<<4)  // Return receipt requested
  2075. MSG_CONFIRMREQ      (1<<5)  // Confirmation receipt requested
  2076. MSG_NODISP          (1<<6)  // Msg may not be displayed to user
  2077.  
  2078.  
  2079. Network Attributes:
  2080. ------------------
  2081. These are the bit values for msghdr_t.netattr:
  2082.  
  2083. MSG_LOCAL           (1<<0)  // Msg created locally
  2084. MSG_INTRANSIT       (1<<1)  // Msg is in-transit
  2085. MSG_SENT            (1<<2)  // Sent to remote
  2086. MSG_KILLSENT        (1<<3)  // Kill when sent
  2087. MSG_ARCHIVESENT     (1<<4)  // Archive when sent
  2088. MSG_HOLD            (1<<5)  // Hold for pick-up
  2089. MSG_CRASH           (1<<6)  // Crash
  2090. MSG_IMMEDIATE       (1<<7)  // Send Msg now, ignore restrictions
  2091. MSG_DIRECT          (1<<8)  // Send directly to destination
  2092. MSG_GATE            (1<<9)  // Send via gateway
  2093. MSG_ORPHAN          (1<<10) // Unknown destination
  2094. MSG_FPU             (1<<11) // Force pickup
  2095. MSG_TYPELOCAL       (1<<12) // Msg is for local use only
  2096. MSG_TYPEECHO        (1<<13) // Msg is for conference distribution
  2097. MSG_TYPENET         (1<<14) // Msg is direct network mail
  2098.  
  2099. Translation Types:
  2100. -----------------
  2101. &&Translation Types
  2102. $$XLATTYPE
  2103.  
  2104. Definition for values of *.xlat[x]:
  2105.  
  2106. XLAT_NONE           0       // No translation/End of translation list
  2107. XLAT_LF2CRLF        1       // Expand sole LF to CRLF
  2108. XLAT_ESCAPED        2       // 7-bit ASCII escaping for ctrl and 8-bit data
  2109. XLAT_HUFFMAN        3       // Static and adaptive Huffman coding compression
  2110. XLAT_LZW            4       // Limpel/Ziv/Welch compression
  2111. XLAT_MLZ78          5       // Modified LZ78 compression
  2112. XLAT_RLE            6       // Run length encoding compression
  2113. XLAT_IMPLODE        7       // Implode compression (PKZIP)
  2114. XLAT_SHRINK         8       // Shrink compression (PKZIP)
  2115.  
  2116. Agent Types:
  2117. -----------
  2118. &&Agent Types
  2119. $$AGENTTYP
  2120.  
  2121. AGENT_PERSON        0       // To or from person
  2122. AGENT_PROCESS       1       // Unknown process, identified by agent name
  2123.  
  2124. Agent types E000h through EFFFh are reserved for Synchronet process types
  2125. (defined specifically by Digital Dynamics).
  2126.  
  2127. Note:
  2128. ----
  2129. Specifically not defined are agent types F000h through FFFFh. These values
  2130. are to be used for user or system defined agent types. Digital Dynamics
  2131. requests that any developers or organizations that wish to have additional
  2132. agent types added to this specification notify Digital Dynamics through any
  2133. of the contact methods listed at the beginning of this document.
  2134.  
  2135. Network Types:
  2136. -------------
  2137. &&Network Types
  2138. $$NETWORKS
  2139.  
  2140. NET_NONE            0       // Locally created
  2141. NET_UNKNOWN         1       // Unknown network type
  2142. NET_FIDO            2       // FTN network
  2143. NET_POSTLINK        3       // PostLink network
  2144. NET_QWK             4       // QWK based network
  2145. NET_INTERNET        5       // The Internet
  2146.  
  2147.  
  2148. Media Types:
  2149. ===========
  2150. &&Media Types
  2151. $$MEDIATYP
  2152.  
  2153. Image Types:
  2154. -----------
  2155.  
  2156. IMAGE_UNKNOWN       0x00    // Use image signature header to determine format
  2157. IMAGE_ASC           0x01    // ASCII text/IBM extended ASCII graphics
  2158. IMAGE_ANS           0x02    // ANSI X3.64 terminal escape sequences
  2159. IMAGE_AVT           0x03    // AVATAR terminal escape sequences
  2160. IMAGE_LVI           0x04    // LVI terminal escape sequences
  2161. IMAGE_GIF           0x05    // Compuserve Graphics Interchange Format (GIF)
  2162. IMAGE_TIF           0x06    // Tagged Image Format (AKA TIFF)
  2163. IMAGE_JPG           0x07    // Joint Photographers Electronics Group (JPEG)
  2164. IMAGE_T16           0x08    // TrueVision 16-bit bitmap (TGA)
  2165. IMAGE_T24           0x09    // TrueVision 24-bit bitmap (TGA)
  2166. IMAGE_T32           0x0a    // TrueVision 32-bit bitmpa (TGA)
  2167. IMAGE_PCX           0x0b    // ZSoft PaintBrush graphics
  2168. IMAGE_BMP           0x0c    // Windows bitmap
  2169. IMAGE_RLE           0x0d    // Windows bitmap (compressed)
  2170. IMAGE_DIB           0x0e    // Display independant bitmap
  2171. IMAGE_PCD           0x0f    // Kodak PhotoCD
  2172. IMAGE_G3F           0x10    // Group 3 FAX
  2173. IMAGE_EPS           0x11    // Ecapsulated PostScript
  2174. IMAGE_RTF           0x12    // Rich text format
  2175. IMAGE_RIP           0x13    // Remote Imaging Protocol Script (RIPscrip)
  2176. IMAGE_NAP           0x14    // NAPLPS
  2177. IMAGE_CDR           0x15    // Corel Draw!
  2178. IMAGE_CGM           0x16    // Computer graphics metafile
  2179. IMAGE_WMF           0x17    // Windows metafile
  2180. IMAGE_DFX           0x18    // Autodesk AutoCAD
  2181.  
  2182.  
  2183. Animation Types:
  2184. ---------------
  2185.  
  2186. ANIM_UNKNOWN        0       // Use file signature header to determine format
  2187. ANIM_FLI            1       // Autodesk animator
  2188. ANIM_FLC            2       // Autodesk
  2189. ANIM_GL             3       // Grasprt
  2190.  
  2191.  
  2192. Video Types:
  2193. -----------
  2194.  
  2195. VIDEO_UNKNOWN       0       // Use file signature header to determine format
  2196. VIDEO_QTIME         1       // Apple Quick-time
  2197. VIDEO_FQTIME        2       // Apple Flattened Quick-time
  2198. VIDEO_AVI           3       // Windows Auto/Video Interleave
  2199. VIDEO_ULT           4       // OS/2 Ultimotion
  2200.  
  2201. Video Compression Types:
  2202. -----------------------
  2203.  
  2204. VCOMP_UNKNOWN       0       // Use file signature header to determine codec
  2205. VCOMP_RLE           1       // Apple animation
  2206. VCOMP_SMC           2       // Apple graphics
  2207. VCOMP_RPZA          3       // Apple video
  2208. VCOMP_KLIC          4       // Captain crunch
  2209. VCOMP_CVID          5       // CinePak
  2210. VCOMP_RT21          6       // Intel indeo R2
  2211. VCOMP_IV31          7       // Intel indeo R3
  2212. VCOMP_YVU9          8       // Intel YVU9
  2213. VCOMP_JPEG          9       // JPEG
  2214. VCOMP_MRLE          10      // Microsoft RLE
  2215. VCOMP_MSVC          11      // Microsoft video 1
  2216.  
  2217.  
  2218. Font Types:
  2219. ----------
  2220.  
  2221. FONT_UNKNOWN        0       // Use file signature header to determine format
  2222. FONT_TTF            1       // Windows TrueType
  2223. FONT_PFB            2       // PostScript Type 1 Font Binary
  2224. FONT_PFM            3       // PostScript Type 1 Font Metric
  2225.  
  2226.  
  2227. Sound Types:
  2228. -----------
  2229.  
  2230. SOUND_UNKNOWN       0       // Use file signature header to determine format
  2231. SOUND_MOD           1       // MOD format
  2232. SOUND_VOC           2       // Sound Blaster VOC format
  2233. SOUND_WAV           3       // Windows 3.1 WAV RIFF format
  2234. SOUND_MID           4       // MIDI format
  2235. SOUND_GMID          5       // General MIDI format (standardized patches)
  2236. SOUND_SMP           6       // Turtle Beach SampleVision format
  2237. SOUND_SF            7       // IRCAM format
  2238. SOUND_AU            8       // Sun Microsystems AU format
  2239.  
  2240.  
  2241. Application Data Types:
  2242. ----------------------
  2243.  
  2244. APPDATA_UNKNOWN     0       // Use file signature header to determine format
  2245. APPDATA_WORDPERFECT 1       // WordPerfect Document
  2246. APPDATA_WKS         2       // Lotus 123 Worksheet (?)
  2247. APPDATA_WK1         3       // Lotus 123 Worksheet rev 1
  2248. APPDATA_WK2         4       // Lotus 123 Worksheet rev 2
  2249. APPDATA_WK3         5       // Lotus 123 Worksheet rev 3
  2250. APPDATA_DBF         6       // dBase III data file
  2251. APPDATA_PDX         7       // Paradox data file
  2252. APPDATA_EXCEL       8       // Excel data file
  2253. APPDATA_QUATRO      9       // Borland Quatro Pro file
  2254. APPDATA_WORD        10      // Microsoft Word
  2255.  
  2256. Message Storage Protocol
  2257. ========================
  2258. &&Message Storage Protocol
  2259. $$STORPROT
  2260.  
  2261.  1. Open SDT, SHD, and SID files read/write deny-none (shareable).
  2262.  
  2263.  2. Determine length of all message data and number of 256 byte blocks
  2264.     required to store the data.
  2265.  
  2266.  3. Open SDA file read/write deny-all.
  2267.  
  2268.  4. If fast allocation mode, seek to end of SDA file and go to step 6.
  2269.  
  2270.  5. Search SDA file for enough consecutive unused blocks to store all of the
  2271.     message data. If found, seek back to beginning of unused blocks. Otherwise
  2272.     stay at end of file.
  2273.  
  2274.  6. Write to the SDA file the number of index entries that are going to point
  2275.     to this data (normally 1) for the number of blocks that will be used. The
  2276.     data block(s) have now been allocated.
  2277.  
  2278.  7. Close the SDA file.
  2279.  
  2280.  8. Determine length of header record and number of 256 byte blocks
  2281.     required to store the record.
  2282.  
  2283.  9. Open SHA file read/write deny-all.
  2284.  
  2285. 10. If fast allocation mode, seek to end of SHA file and go to step 12.
  2286.  
  2287. 11. Search SHA file for enough consequetive unused blocks to store all of the
  2288.     header record. If found, seek back to beginning of unused blocks. Otherwise
  2289.     stay at end of file.
  2290.  
  2291. 12. Write to the SHA file a 1 (single byte) for each block that will be used.
  2292.     The header block(s) have now been allocated.
  2293.  
  2294. 13. Close the SHA file.
  2295.  
  2296. 14. Lock message base header in SHD file.
  2297.  
  2298. 15. Read SHD base header #1 (config info).
  2299.  
  2300. 16. Increment the total number of messages and last message number in header.
  2301.  
  2302. 17. Write SHD base header #1 (config info).
  2303.  
  2304. 18. Write header record to SHD file.
  2305.  
  2306. 19. Write index record to SID file.
  2307.  
  2308. 20. Unlock SHD base header.
  2309.  
  2310. 21. Write message data to SDT file.
  2311.  
  2312.  
  2313. Message Retrieval Protocol
  2314. ==========================
  2315. &&Message Retrieval Protocol
  2316. $$READPROT
  2317.  
  2318.  1. Open SDT, SHD, and SID files read/write deny-none (shareable).
  2319.  
  2320.  2. Read index record from SID file.
  2321.  
  2322.  3. Seek to the byte offset in the SHD file specified in the index record.
  2323.  
  2324.  4. Lock the message header record.
  2325.  
  2326.  5. Read the message header record.
  2327.  
  2328.  6. Unlock the message header record.
  2329.  
  2330.  7. Compare the message number to the one specified in the index record. If
  2331.     they don't match, re-read the index record and goto step 3. If they
  2332.     continue to mismatch, the index has been corrupted and must be recreated.
  2333.  
  2334.  8. For each data field specified in the header, seek to the byte offset
  2335.     in the SDT file plus the offset specified in the data field, read from
  2336.     the SDT file the length (in bytes) specified in the data field.
  2337.  
  2338.  
  2339. SMBUTIL
  2340. =======
  2341. &&SMBUTIL
  2342. $$SMBUTIL_
  2343.  
  2344. SMBUTIL is a utility that can perform various functions on an SMB format
  2345. message base. The primary purpose of SMBUTIL is as an example to C programmers
  2346. of how to use the SMBLIB functions to access and modify an SMB message base.
  2347. The complete C source code for SMBUTIL is included and functions from it can
  2348. be used or modified by developers at their own discretion. The following files
  2349. make up SMBUTIL:
  2350.  
  2351. SMBUTIL.EXE     Compiled and linked (ready to run)
  2352. SMBUTIL.C       C functions
  2353. SMBUTIL.H       C definitions and variable prototypes
  2354. SMBUTIL.MAK     Makefile (for Borland C++)
  2355. CRC32.H         C header file for CRC-32 calculations
  2356.  
  2357. The usage syntax is as follows:
  2358.  
  2359. SMBUTIL [/opts] cmd smb_filespec.shd
  2360.  
  2361. where cmd is one or more of the following:
  2362.  
  2363.        l[n] = list msgs starting at number n
  2364.        r[n] = read msgs starting at number n
  2365.        v[n] = view msg headers starting at number n
  2366.        k[n] = kill (delete) n msgs
  2367.        i<f> = import from text file f
  2368.        s    = display msg base status
  2369.        c    = change msg base status
  2370.        m    = maintain msg base - delete old msgs and msgs over max
  2371.        p    = pack msg base
  2372.  
  2373. where opts is one or more of the following:
  2374.  
  2375.        a    = always (force) packing
  2376.        f    = fast msg creation mode
  2377.        d    = disable duplicate message checking
  2378.        z<n> = set time zone (n=min +/- from UT or 'EST','EDT','CST',etc)
  2379.  
  2380. and smb_filespec is the base filename or file specification (wildcards) for the
  2381. message base. If wildcards are used, the ".SHD" extension must be specified.
  2382.  
  2383. An example command line:
  2384.  
  2385. SMBUTIL R FORSALE
  2386.  
  2387. would read all the messages in the forsale message base. If the forsale message
  2388. base files are not stored in the current directory, the complete path must be
  2389. specified. (i.e. smbutil r c:\msgs\forsale)
  2390.  
  2391. SMBUTIL MP C:\SBBS\DATA\SUBS\*.SHD
  2392.  
  2393. would maintain and pack all the message bases found in the C:\SBBS\DATA\SUBS
  2394. directory.
  2395.  
  2396. CHKSMB
  2397. ======
  2398. &&CHKSMB
  2399. $$CHKSMB__
  2400.  
  2401. CHKSMB is a utility that performs a comprehensive analysis of a message base
  2402. to find any possible errors. It does not "fix" a message base if any errors
  2403. are found, it only reports the specific errors (and exits with a non-zero
  2404. error level).
  2405.  
  2406. C source code for CHKSMB is also included as an example to programmers of how
  2407. to use SMBLIB functions.
  2408.  
  2409. The usage syntax is as follows:
  2410.  
  2411. CHKSMB [/opts] smb_filespec.shd
  2412.  
  2413. where opts is one or more of the following:
  2414.  
  2415.         q   = quiet mode (no beeps)
  2416.         s   = stop after an errored message base (for use with wildcards)
  2417.         p   = pause after an errored message base (wait for key press)
  2418.  
  2419. An example command line:
  2420.  
  2421. CHKSMB /QP C:\SBBS\DATA\SUBS\*.SHD
  2422.  
  2423. would check all the message bases in the C:\SBBS\DATA\SUBS directory, without
  2424. beeping on errors, and pausing after an errored message base.
  2425.  
  2426. SMBLIB
  2427. ======
  2428. &&SMBLIB
  2429. $$SMBLIB__
  2430.  
  2431. SMBLIB is a library of C functions for accessing and storing messages in an
  2432. SMB format message base. It can eliminate much of the development time for
  2433. developers that wish to use the library in whole or in part, or use the
  2434. functions as examples for their own message base function library. The library
  2435. consists of the following files:
  2436.  
  2437. SMBDEFS.H       Constant definitions, macros, and data types
  2438. SMBLIB.H        Function prototypes
  2439. SMBLIB.C        Function definitions
  2440. SMBVARS.C       Global variable definitions (doubles as declaration file)
  2441.  
  2442. For developers to use this library with their program, they must include the
  2443. "SMBLIB.H" header file at the top of each C file that uses any of the library
  2444. functions, global variables, data types, macros, constants. This can be done
  2445. by simply add the following line to each .C file:
  2446.  
  2447. #include "smblib.h"
  2448.  
  2449. If SMBLIB.H is included, there is no need to include SMBDEFS.H or SMBVARS.C.
  2450.  
  2451. To link the library functions and variables with a main program, the files
  2452. SMBVARS.OBJ and SMBLIB.OBJ must be linked with the main program .OBJ files.
  2453. If the operating system is DOS, be sure that all .OBJ files are compiled for
  2454. the same memory model.
  2455.  
  2456. An example MAKEFILE for compiling and linking SMBUTIL with Borland C++ is
  2457. included.
  2458.  
  2459. SMBDEFS.H
  2460. =========
  2461. &&SMBDEFS.H
  2462. $$SMBDEFS_
  2463.  
  2464. The SMBDEFS.H file contains important constant definitions and data types (also
  2465. defined in this document). If ever this document and SMBDEFS.H are inconsistent
  2466. with each other, then SMBDEFS.H is to be considered correct and this document
  2467. in error. If such a discrepency is found, please notifiy Digital Dynamics so it
  2468. can be corrected in a future revision of the specification.
  2469.  
  2470. Most notable of the data types is a structure called smbmsg_t (not defined
  2471. in this document). It contains the fixed and variable portions of a message's
  2472. header record as well as convenience pointers to the sender's name
  2473. (smbmsg_t.to), recipient's name (smbmsg_t.from), network addresses, and more.
  2474. If multiple SENDER header fields are included (for example), then smbmsg_t.to
  2475. will point to the last SENDER header field in the header record. Convenience
  2476. pointers for other data items work in the same fasion if multiple header fields
  2477. of the same type exist in the header record.
  2478.  
  2479. Variables of the smbmsg_t data type (and pointers to variables of smbmsg_t
  2480. type) are used as arguments to many of the SMBLIB functions.
  2481.  
  2482. SMBVARS.C
  2483. =========
  2484. &&SMBVARS.C
  2485. $$SMBVARS_
  2486.  
  2487. The SMBVARS.C file contains definitions of the global variables used by the
  2488. SMBLIB functions. It is a fairly small file since their are a small number of
  2489. global variables (by design). This file is used for both definitions and
  2490. declarations, so no "extern" declarations need to be made in developers source
  2491. code as long as SMBVARS.C or (preferably) SMBLIB.H is included in the source
  2492. code.
  2493.  
  2494. SMBLIB.H
  2495. =======
  2496. &&SMBLIB.H
  2497. $$SMBLIB.H
  2498.  
  2499. The SMBLIB.H file contains prototypes of all the functions in the SMBLIB.C
  2500. file. It is necessary to include this file in C source code if any of the
  2501. SMBLIB functions are used. The following C source line will include this file:
  2502.  
  2503. #include "smblib.h"
  2504.  
  2505. and should be placed near the top of all C source files that use SMBLIB
  2506. functions, variables, constants, or data types.
  2507.  
  2508. Function prototypes are necessary for compilers to know the correct calling
  2509. syntax of a function and detect incorrect usage. Prototypes are also useful
  2510. as a quick reference for programmers as to the correct calling syntax of a
  2511. specific function.
  2512.  
  2513. SMBLIB.C
  2514. =======
  2515. &&SMBLIB.C
  2516. $$SMBLIB.C
  2517.  
  2518. The SMBLIB.C file contains the actual SMBLIB library functions. This source
  2519. file is not a stand alone program, but instead must be compiled and linked
  2520. with a main source file to create the executable program.
  2521.  
  2522. The functions in this file are organized in a logical order, but their order
  2523. is actually irrelevant to the compiling, linking, and execution of the
  2524. resulting program.
  2525.  
  2526. A comment block preceeds each function, explaining what the function does,
  2527. how the passed parameters are used, and what the return code (if any)
  2528. indicates. A more detailed explanation of each function is included here:
  2529.  
  2530. int smb_open(int retry_time)
  2531. --------------
  2532. The smb_open() function must be called before the message base is accessed
  2533. (read from or written to). The parameter, retry_time, is the maximum number
  2534. of seconds to wait while retrying to lock the message base header. The global
  2535. variable smb_file must be initialized with the path and base filename of the
  2536. message base. This function returns 0 on success, 1 if the .SDT file could not
  2537. be opened, 2 if the .SHD file could not be opened, and 3 if the .SID file could
  2538. not be opened. If the message base header could not be locked, this function
  2539. returns -1. If the message base ID is incorrect, it returns -2. And if the
  2540. message base is of an incompatible version, it returns -3.
  2541.  
  2542. The errno global variable (standard of most C libraries) will most likely
  2543. contain the error code for open failure.
  2544.  
  2545. int smb_open_da(int retry_time)
  2546. -------------------------------
  2547. The smb_open_da() function is used to open the data block allocation file for
  2548. writing messages to a message base. The parameter, retry_time, is the maximum
  2549. number of seconds to wait while retrying to open the file. This function
  2550. returns 0 on success. -1 is returned if an open error other than "Access
  2551. Denied" is returned from the operating system, and the global variable errno
  2552. will contain the error code. -2 is returned if the retry_time has been
  2553. reached, and -3 is returned if the file descriptor could not be converted to
  2554. a stream by the fdopen() function.
  2555.  
  2556. fclose(smb_sda) should be called immediately after all necessary file access
  2557. has been completed.
  2558.  
  2559. int smb_open_ha(int retry_time)
  2560. -------------------------------
  2561. The smb_open_ha() function is used to open the header block allocation file for
  2562. writing messages to a message base. The parameter, retry_time, is the maximum
  2563. number of seconds to wait while retrying to open the file. This function
  2564. returns 0 on success. -1 is returned if an open error other than "Access
  2565. Denied" is returned from the operating system, and the global variable errno
  2566. will contain the error code. -2 is returned if the retry_time has been
  2567. reached, and -3 is returned if the file descriptor could not be converted to
  2568. a stream by the fdopen() function.
  2569.  
  2570. fclose(smb_sha) should be called immediately after all necessary file access
  2571. has been completed.
  2572.  
  2573. int smb_create(ulong max_crcs, ulong max_msgs, ushort max_age, int retry_time)
  2574. ------------------------------------------------------------------------------
  2575. The smb_create() function is used to create a new message base or reset an
  2576. existing message base. The parameters max_crcs, max_msgs, and max_age are used
  2577. to set the initial status of the message base status header. The parameter,
  2578. retry_time is the maximum number of seconds to wait while retrying to lock the
  2579. message base header. This functions returns 0 on success or 1 if the message
  2580. base header could not be locked.
  2581.  
  2582. int smb_trunchdr(int retry_time)
  2583. --------------------------------
  2584. The smb_trunchdr() function is used to truncate the header file when packing
  2585. the message base and writing the new header information back to the header
  2586. file. The parameter, retry_time is the maximum number of seconds to wait while
  2587. retrying to truncate the header file. Returns 0 on success, -1 if error was
  2588. other than "Access Denied", or -2 if retry_time reached.
  2589.  
  2590. int smb_locksmbhdr(int retry_time)
  2591. ----------------------------------
  2592. The smb_locksmbhdr() function is used to lock the first message base (status)
  2593. header. The parameter, retry_time is the number of seconds to wait while
  2594. retrying to lock the header. The smb_unlocksmbhdr() function should always be
  2595. used to unlock the header after accessing the message base header (usually
  2596. with smb_getstatus() and/or smb_putstatus()). Returns 0 if successful, -1 if
  2597. unsuccessful.
  2598.  
  2599. int smb_unlocksmbhdr()
  2600. ----------------------
  2601. The smb_unlocksmbhdr() function is used to unlock a previously locked message
  2602. base header (using smb_lockmsghdr()). Returns 0 on success, non-zero on
  2603. failure.
  2604.  
  2605. int smb_getstatus(smbstatus_t *hdr)
  2606. -----------------------------------
  2607. The smb_getstatus() function is used to read the status message base header
  2608. into the hdr structure. Returns 0 on success, 1 on failure.
  2609.  
  2610. int smb_putstatus(smbstatus_t hdr)
  2611. ----------------------------------
  2612. The smb_putstatus() function is used to write the status information to the
  2613. first message base header. The parameter hdr, contains the status information
  2614. to be written. Returns 0 on success, 1 on failure.
  2615.  
  2616. int smb_getmsgidx(smbmsg_t *msg)
  2617. --------------------------------
  2618. The smb_getmsgidx() function is used to get the byte offset for a specific
  2619. message header in the message header file based on the message base index.
  2620.  
  2621. If msg->hdr.number is non-zero when this function is called, then the index
  2622. will be searched for this message number. If the message number is found in
  2623. the index, the msg->idx.offset is set to the byte offset of the message header
  2624. record in the header file and msg->offset is set to the record offset of the
  2625. index record in the index file, and the function returns 0. If the message
  2626. number is not found in the index, the function returns 1.
  2627.  
  2628. If msg->hdr.number is zero, msg->idx.offset and msg->idx.number are obtained
  2629. from the index record at record offset msg->offset. If msg->offset is an
  2630. invalid record offset when this function is called, the function returns 1.
  2631. Otherwise, the function returns 0.
  2632.  
  2633. int smb_getmsghdrlen(smbmsg_t msg)
  2634. ----------------------------------
  2635. The smb_getmsghdrlen() function is used to calculate the total length of
  2636. message header msg including both fixed and variable length portions. This
  2637. function returns the length of the header record in bytes.
  2638.  
  2639. long smb_getmsgdatlen(smbmsg_t msg)
  2640. -----------------------------------
  2641. The smb_getmsgdatlen() function is used to calculate the total length of the
  2642. data for message msg. This function returns the length of all data fields
  2643. combined.
  2644.  
  2645. int smb_lockmsghdr(smbmsg_t msg, int retry_time)
  2646. ------------------------------------------------
  2647. The smb_lockmsghdr() function is used to lock the header record for message
  2648. msg. The parameter retry_time is the maximum number of seconds to wait while
  2649. retrying to lock the header. Returns 0 on success, -1 on failure. The function
  2650. smb_unlockmsghdr() should immediately be called after accessing the message
  2651. header (usually with smb_getmsghdr() or smb_putmsghdr()).
  2652.  
  2653. int smb_getmsghdr(smbmsg_t *msg)
  2654. --------------------------------
  2655. The function smb_getmsghdr() is used to read the header record for message
  2656. msg. msg->idx.offset must be initialized to the byte offset of the header
  2657. record in the header file before this function is called. The function
  2658. smb_freemsgmem() must be called to free the memory allocated by this function
  2659. for the header and data felds. This function returns 0 on success, -1 if
  2660. the fixed portion of the message header record could not be read, -2 if the
  2661. message header ID was incorrect, -3 if memory could not be allocated, -4
  2662. if a data field could not be read, -5 if the fixed length portion of a header
  2663. field could not be read, -6 if the variable length portion of a header field
  2664. could not be read, -7 if one or more of the mandatory header fields (SENDER,
  2665. RECIPIENT, or SUBJECT) are missing, -8 if total_dfields extends beyond the
  2666. end of the header reocord, or -9 if incompatible header version.
  2667.  
  2668. Several convenience pointers in the msg structure are initialized by this
  2669. function to point to the last occurance of the SENDER (msg->from), RECIPIENT
  2670. (msg->to), SUBJECT (msg->subj), etc.
  2671.  
  2672. int smb_unlockmsghdr(smbmsg_t msg)
  2673. ----------------------------------
  2674. The smb_unlockmsghdr() function is used to unlock a previously locked message
  2675. header (with smb_lockmsghdr()). This function returns 0 on success, non-zero
  2676. on failure.
  2677.  
  2678. int smb_addcrc(ulong max_crcs, ulong crc, int retry_time)
  2679. ---------------------------------------------------------
  2680. The smb_addcrc() function is used to add a CRC-32 to the CRC history file
  2681. for a message base, automatically checking for duplicates. The parameter
  2682. max_crcs should be the max_crcs defined in the status header of the message
  2683. base. The parameter crc, is the CRC-32 of the TEXT_BODY and TEXT_SOUL data
  2684. fields for the message. The parameter retry_time is the maximum number of
  2685. seconds to wait when retrying to open the CRC history file.
  2686.  
  2687. This function returns -1 if there was an open error, -2 if the retry_time
  2688. was reached, -3 if there was a memory allocation error, 1 if the CRC already
  2689. exists in the CRC history file (indicating a duplicate message), or 0 on
  2690. success (and no duplicate).
  2691.  
  2692. int smb_hfield(smbmsg_t *msg, ushort type, ushort length, void *data)
  2693. ---------------------------------------------------------------------
  2694. The smb_hfield() function is used to add a header field to the structure msg.
  2695. The parameters type, length, and data, must be specified according to the
  2696. header field values listed in this specification. This function returns 0
  2697. on success, non-zero on memory allocation error. The function smb_freemsgmem()
  2698. must be called to free the memory allocated by this function.
  2699.  
  2700. int smb_dfield(smbmsg_t *msg, ushort type, ulong length)
  2701. --------------------------------------------------------
  2702. The smb_dfield() function is used to add a data field to the structure msg.
  2703. The parameters type and length must be specified according to the data field
  2704. values listed in this specification. This function returns 0 on success,
  2705. non-zero on memory allocation error. The function smb_freemsgmem() must be
  2706. called to free the memory allocated by this function.
  2707.  
  2708. int smb_addmsghdr(smbmsg_t *msg, smbstatus_t *status, int fast, int retry_time)
  2709. -------------------------------------------------------------------------------
  2710. The smb_addmsghdr() function is used to add a new message header to the message
  2711. header file. The msg and status structures are updated to reflect the new
  2712. total messages, last message number, etc. The fast parameter is used to
  2713. indicate if the fast allocation mode should be used. If the fast parameter is
  2714. 0 (off), the header block allocation file will be searched for unused block(s)
  2715. to store this header. If the fast parameter is 1 (on), the header is stored at
  2716. the end of the header file. Returns 0 on success, non-zero on failure. The
  2717. parameter retry_time is the maximum number of seconds to wait while retrying
  2718. to lock and open files.
  2719.  
  2720. int smb_putmsg(smbmsg_t msg)
  2721. ----------------------------
  2722. Ths smb_putmsg() function calls both the smb_putmsghdr() and smb_putmsgidx()
  2723. functions to write the header and index elements of a message to the
  2724. appropriate files. Returns 0 on success, non-zero on failure.
  2725.  
  2726. int smb_putmsgidx(smbmsg_t msg)
  2727. -------------------------------
  2728. The smb_putmsgidx() function is used to store a message index in the message
  2729. index file. The message index can be for a new message or an existing
  2730. message. Returns 0 on success, non-zero on failure.
  2731.  
  2732. int smb_putmsghdr(smbmsg_t msg)
  2733. -------------------------------
  2734. The smb_putmsghdr() function is used to store a message header in the message
  2735. header file. The message header can be for a new message or an existing
  2736. message. Returns 0 on success, non-zero on failure.
  2737.  
  2738. void smb_freemsgmem(smbmsg_t msg)
  2739. ---------------------------------
  2740. Frees allocated memory for the header and data fields in the msg structure.
  2741. This function must be called to free the memory allocated by the functions
  2742. smb_hfield(), smb_dfield(), and smb_getmsghdr().
  2743.  
  2744. long smb_hdrblocks(ulong length)
  2745. --------------------------------
  2746. The smb_hdrblocks() function is used to calculate the number of blocks
  2747. required to store a message header of length size (in bytes). This function
  2748. returns the number of blocks required.
  2749.  
  2750. long smb_datblocks(ulong length)
  2751. --------------------------------
  2752. The smb_datblocks() function is used to calculate the number of blocks
  2753. required to store message data of length size (in byte). This function returns
  2754. the number of blocks required.
  2755.  
  2756. long smb_allochdr(ulong length)
  2757. -------------------------------
  2758. The smb_allochdr() function is used to search for free blocks to store a
  2759. message header of length bytes and mark the free blocks as allocated in the
  2760. header allocation file. This function returns the byte offset to the header
  2761. record or a negative number on error. The function smb_open_ha() should be
  2762. called prior to calling this function and fclose(sha_fp) should be called
  2763. after.
  2764.  
  2765. long smb_fallochdr(ulong length)
  2766. --------------------------------
  2767. The smb_fallochdr() function works exactly the same as the smb_allochdr()
  2768. function except it is much faster because the header allocation file is not
  2769. searched for free blocks.
  2770.  
  2771. long smb_allocdat(ulong length, ushort headers)
  2772. -----------------------------------------------
  2773. The smb_allocdat() function is used to search for free blocks to store length
  2774. amount of data for a message. The parameter headers, indicates the number of
  2775. message headers that are associated with this data. Normally, the headers
  2776. parameter will be 1, unless this message is part of a mass mailing. The offset
  2777. to the allocated data blocks is returned, or a negative value on error. The
  2778. function smb_open_da() should be called prior to calling this function and
  2779. fclose(sda_fp) should be called after.
  2780.  
  2781. long smb_fallocdat(ulong length, ushort headers)
  2782. ------------------------------------------------
  2783. The smb_fallocdat() function works exactly the same as the smb_allocdat()
  2784. function except it is much faster because the data allocation file is not
  2785. searched for free blocks.
  2786.  
  2787. int smb_incdat(ulong offset, ulong length, ushort headers)
  2788. ----------------------------------------------------------
  2789. The smb_incdat() function is used to increment the header counter in the data
  2790. allocation file for the data starting at the byte offset and length size in
  2791. bytes. The parameter headers, indicates the number of headers to add to the
  2792. current allocation value in the data allocation file. Returns 0 on success,
  2793. non-zero on failure.
  2794.  
  2795. int smb_freemsg(smbmsg_t msg, smbstatus_t status)
  2796. -------------------------------------------------
  2797. The smb_freemsg() function is used to free the memory allocated for the header
  2798. and data fields in the msg structure. Returns 0 on success, non-zero on
  2799. failure. The parameter, status, must be the current status from the message
  2800. base header for this message base.
  2801.  
  2802. int smb_freemsgdat(ulong offset, ulong length, ushort headers)
  2803. --------------------------------------------------------------
  2804. The smb_freemsgdat() function is used to decrement the data block allocation
  2805. records in the data allocation file associated with the data in the data file
  2806. by the value of the headers parameter (normally 1). The parameter offset
  2807. indicates the byte offset to the beginning of the message data in the data
  2808. file and the parameter length is the total length of the message data.
  2809. Returns 0 on success, non-zero on failure.
  2810.  
  2811. int smb_freemsghdr(ulong offset, ulong length)
  2812. ----------------------------------------------
  2813. The smb_freemsghdr() function is used to set the header block allocation
  2814. records in the header allocation file to 0 (indicated non-allocated block).
  2815. The parameter offset indicates the byte offset to the beginning of the header
  2816. record being freed and the parameter length indicates the total length of the
  2817. header record. Returns 0 on success, non-zero on failure.
  2818.  
  2819. Bibliography
  2820. ============
  2821. &&Bibliography
  2822. $$BIBLIOGR
  2823.  
  2824. Title     : The C Programming Language
  2825. Publisher : Prentice Hall
  2826. Author    : Brian W. Kernighan and Dennis M. Ritchie
  2827.  
  2828. Document  : ARPANET Request for Comments (RFC) #822
  2829. Title     : Standard for the Format of ARPA Internet text messages
  2830. Publisher : SRI International
  2831. Author    : David H. Crocker, University of Delaware
  2832.  
  2833. Document  : FTS-0001
  2834. Publisher : FSC
  2835. Author    : Randy Bush, Pacific Systems Group
  2836.  
  2837. Document  : FTS-0004
  2838. Title     : EchoMail Specification
  2839. Publisher : FSC
  2840. Author    : Bob Hartman
  2841.  
  2842. Document  : FTS-0009
  2843. Title     : A standard for unique message identifiers and reply chain linkage
  2844. Publisher : FSC
  2845. Author    : Jim Nutt
  2846.  
  2847. Document  : FSC-00046
  2848. Title     : A Product Idenfifier for FidoNet Message Handlers
  2849. Publisher : FSC
  2850. Author    : Joaquim H. Homrighausen
  2851.  
  2852. Document  : FSC-00053
  2853. Title     : Specifications for the ^aFLAGS field
  2854. Publisher : FSC
  2855. Author    : Joaquim H. Homrighausen
  2856.  
  2857.  
  2858. Implementations
  2859. ===============
  2860. &&Implementations
  2861. $$IMPLEMEN
  2862.  
  2863. Product   : Synchronet Multinode BBS Software
  2864. Developer : Digital Dynamics
  2865. Level     : II
  2866. Version   : 2.00
  2867.  
  2868. Product   : Synchornet/FidoNet Import/Export Utility (SBBSFIDO)
  2869. Developer : Digital Dynamics
  2870. Level     : II
  2871. Version   : 2.00
  2872.  
  2873. Product   : Synchronet UTI (Universal Text Interface) Driver
  2874. Developer : Digital Dynamics
  2875. Level     : II
  2876. Version   : 2.00
  2877.